plan_driven 0.1.0 → 0.2.0

data/lib/plan_driven/renderer/markdown.rb

@@ -23,6 +23,7 @@ module PlanDriven
         parts << "## Tickets and pull requests\n\n#{delivery_table(plan)}"
         parts << "## Acceptance criteria and proof\n\n#{Evidence.matrix_markdown(plan)}"
         parts << "## Checks run on each pull request\n\n#{guard_findings(plan)}"
+        parts << "## Tokens and cost\n\n#{usage_table(plan)}"
         parts << "## Approvals\n\n#{approval_history(plan)}"
         parts << "## Timeline\n\n#{timeline(plan)}"
         parts << "## The approved plan\n\nThe plan this delivery implements is in `plan.md`, revision #{plan.revision}."
@@ -116,8 +117,32 @@ module PlanDriven
         table(%w[When Subject Role Decision By Note], rows)
       end
 
+      def usage_table(plan)
+        rows = Usage.rows(plan)
+        return "No token usage recorded." if rows.empty?
+
+        "#{table(%w[Step Ticket Model Input Output Cache Time Cost], rows.map { |row| usage_row(row) })}\n\n" \
+          "#{usage_total(Usage.totals(rows))}"
+      end
+
+      def usage_row(row)
+        tokens = row.tokens.transform_values { |count| Usage.format_tokens(count) }
+        cache = Usage.format_tokens(row.tokens["cache_write_tokens"] + row.tokens["cache_read_tokens"])
+        time = row.duration_ms ? "#{(row.duration_ms / 60_000.0).round(1)} min" : "-"
+        [row.step.to_s, row.ticket || "-", row.model.to_s, tokens["input_tokens"], tokens["output_tokens"], cache, time,
+         Usage.format_cost(row.cost)]
+      end
+
+      def usage_total(totals)
+        tokens = Usage.format_tokens(totals[:total_tokens])
+        return "**Total: #{tokens} tokens, #{Usage.format_cost(totals[:cost])}**" if totals[:cost]
+
+        "**Total: #{tokens} tokens.** No price is set for #{totals[:unpriced].join(", ")}; " \
+          "add it to `config.token_prices` to see dollars."
+      end
+
       def timeline(plan)
-        plan.events.map do |event|
+        plan.events.where.not(name: %w[llm.usage agent.usage]).map do |event|
           target = event.ticket ? " #{event.ticket.key}" : ""
           "- #{event.created_at.strftime("%-d %b %Y %H:%M")} · #{event.name}#{target} · #{event.actor}"
         end.join("\n")

data/lib/plan_driven/template.rb

@@ -15,6 +15,11 @@ module PlanDriven
       def drafted?
         source == :draft
       end
+
+      # The question as the interview shows it, in the terminal and in the wizard.
+      def prompt
+        required ? question.to_s : "#{question} (optional)"
+      end
     end
 
     GROUPS = ["Overview", "Background", "Architectural changes", "Work overview", "Risks", "Testing"].freeze
@@ -68,7 +73,7 @@ module PlanDriven
       { key: "when", title: "When", group: "Overview", source: :ask, required: false, min_words: 0,
         question: "When is it needed? (date, milestone, or leave empty)", guidance: "Target date or milestone." },
       { key: "background", title: "Background", group: "Background", source: :ask, required: false, min_words: 0,
-        question: "Links, PRDs, existing tickets, earlier decisions (optional)",
+        question: "Links, PRDs, existing tickets, earlier decisions",
         guidance: "Links, product documents, related tickets and earlier decisions." },
       { key: "existing_data_structure", title: "Existing Data Structure", group: "Background", source: :draft,
         required: true, min_words: 30,
@@ -91,7 +96,7 @@ module PlanDriven
         source: :draft, required: true, min_words: 5,
         guidance: "Queues, external services, feature flags and rollout order. Say so when there are none." },
       { key: "out_of_scope", title: "Out of Scope", group: "Work overview", source: :ask, required: false,
-        min_words: 0, question: "What is explicitly out of scope? (optional)",
+        min_words: 0, question: "What is explicitly out of scope?",
         guidance: "What this plan deliberately doesn't do." },
       { key: "risks", title: "Risks", group: "Risks", source: :draft, required: true, min_words: 15,
         guidance: "The main risks as a list, and how each is mitigated." },

data/lib/plan_driven/usage.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # What a plan cost to deliver: tokens for every model call and agent run, recorded as events
+  # (`llm.usage`, `agent.usage`), and dollars when config.token_prices has a price for the model.
+  # Prices change and differ per account, so the gem ships none: put in what your provider charges.
+  module Usage
+    FIELDS = %w[input_tokens output_tokens cache_write_tokens cache_read_tokens].freeze
+
+    Row = Struct.new(:step, :ticket, :model, :calls, :tokens, :duration_ms, :cost, keyword_init: true) do
+      def total_tokens
+        tokens.values.sum
+      end
+    end
+
+    module_function
+
+    # Dollars for these tokens, or nil when the model has no price. Prices are per million tokens:
+    #   config.token_prices = { "your-model-id" => { input: 3.0, output: 15.0, cache_write: 3.75, cache_read: 0.3 } }
+    def cost(model, tokens, config: PlanDriven.configuration)
+      price = config.token_prices.to_h.transform_keys(&:to_s)[model.to_s] or return
+      price = price.transform_keys(&:to_s)
+      FIELDS.sum { |field| tokens[field].to_i * price.fetch(field.delete_suffix("_tokens"), 0).to_f } / 1_000_000.0
+    end
+
+    # What the metered model spent in one step, as an `llm.usage` event.
+    def record_llm(plan, llm, step, actor:)
+      spent = llm.take
+      return if spent["calls"].zero?
+
+      plan.log!("llm.usage", actor: actor, step: step, model: llm.model, **spent.symbolize_keys)
+    end
+
+    # One finished agent run. Usage is bookkeeping: a provider that can't report it mustn't stop
+    # the ticket moving.
+    def record_agent(ticket, run, agents, actor:, config: PlanDriven.configuration)
+      tokens = agents.respond_to?(:usage) ? agents.usage(ticket.agent_id, run.id) : {}
+      step = ticket.plan.events.exists?(name: "agent.usage", ticket: ticket) ? "agent follow-up" : "agent run"
+      ticket.plan.log!("agent.usage", actor: actor, ticket: ticket, step: step, run: run.id,
+                                      model: config.agent_model || "#{config.agent_provider} default",
+                                      calls: 1, duration_ms: run.duration_ms, **tokens.to_h.symbolize_keys)
+    rescue Error => e
+      ticket.plan.log!("agent.usage", actor: actor, ticket: ticket, run: run.id, error: e.message[0, 200])
+    end
+
+    def tokens_from(payload)
+      FIELDS.to_h { |field| [field, payload.to_h[field].to_i] }
+    end
+
+    def rows(plan, config: PlanDriven.configuration)
+      plan.events.where(name: %w[llm.usage agent.usage]).order(:created_at).map do |event|
+        payload = event.payload.to_h
+        tokens = tokens_from(payload)
+        Row.new(step: payload["step"], ticket: event.ticket&.key, model: payload["model"], calls: payload["calls"].to_i,
+                tokens: tokens, duration_ms: payload["duration_ms"],
+                cost: cost(payload["model"], tokens, config: config))
+      end
+    end
+
+    def totals(rows)
+      tokens = FIELDS.to_h { |field| [field, rows.sum { |row| row.tokens[field] }] }
+      costs = rows.map(&:cost)
+      { tokens: tokens, total_tokens: tokens.values.sum, cost: costs.any?(&:nil?) ? nil : costs.sum,
+        priced_cost: costs.compact.sum, unpriced: rows.select { |row| row.cost.nil? }.map(&:model).uniq }
+    end
+
+    def format_tokens(count)
+      count >= 1_000_000 ? format("%.2fM", count / 1_000_000.0) : count.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+    end
+
+    def format_cost(cost)
+      cost ? format("$%.2f", cost) : "-"
+    end
+  end
+
+  # Wraps any model client and counts what each step spends, so Delivery can record it.
+  class MeteredLLM
+    def initialize(llm)
+      @llm = llm
+      reset
+    end
+
+    def chat(**options)
+      reply = @llm.chat(**options)
+      @calls += 1
+      @input += reply.input_tokens.to_i
+      @output += reply.output_tokens.to_i
+      reply
+    end
+
+    def label
+      @llm.label
+    end
+
+    def model
+      label.split("/", 2).last
+    end
+
+    # What was spent since the last take, as an event payload.
+    def take
+      spent = { "calls" => @calls, "input_tokens" => @input, "output_tokens" => @output }
+      reset
+      spent
+    end
+
+    private
+
+    def reset
+      @calls = 0
+      @input = 0
+      @output = 0
+    end
+  end
+end

data/lib/plan_driven/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PlanDriven
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/plan_driven/wizard/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Wizard
+    # Mounted by the install generator, in development only:
+    #
+    #   mount PlanDriven::Wizard::Engine, at: "/plan_driven" if Rails.env.development?
+    class Engine < ::Rails::Engine
+      isolate_namespace PlanDriven::Wizard
+      engine_name "plan_driven_wizard"
+      config.root = File.expand_path("../../..", __dir__)
+
+      # Keys pasted on the Configuration page go to `plan-driven connect` on stdin, never to the log.
+      initializer "plan_driven_wizard.filter_parameters" do |app|
+        app.config.filter_parameters += [:api_key]
+      end
+    end
+  end
+end

data/lib/plan_driven/wizard.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "securerandom"
+require "shellwords"
+
+module PlanDriven
+  # The browser wizard at /plan_driven. Every button runs a real `plan-driven` command in the
+  # background and streams its output to the page, so the wizard can do nothing the CLI can't,
+  # and the terminal panel shows exactly which command ran.
+  module Wizard
+    # The commands the wizard may run, built from form fields. Nothing else reaches a shell:
+    # arguments are passed as an array, never interpolated.
+    module Commands
+      PLAN_ONLY = %w[check submit pdf status evidence report usage log].freeze
+
+      BUILDERS = {
+        "doctor" => ->(_p) { [] },
+        "new" => ->(p) { [required(p, "title")] },
+        "edit" => ->(p) { [plan(p), section(p), "--from", required(p, "file")] },
+        "redraft" => ->(p) { [plan(p), section(p), required(p, "instruction")] },
+        "approve" => ->(p) { [plan(p), *role(p), *note(p)] },
+        "reject" => ->(p) { [plan(p), *role(p), "--note", required(p, "note")] },
+        "tickets" => ->(p) { [plan(p), *p["instruction"].to_s.strip.presence] },
+        "approve-tickets" => ->(p) { [plan(p), *role(p)] },
+        "develop" => ->(p) { [plan(p), *Array(p["tickets"]).map { |key| ticket_key(key) }] },
+        "review" => ->(p) { [ticket(p)] },
+        "merge" => ->(p) { [ticket(p)] },
+        "approve-pr" => ->(p) { [ticket(p), *note(p)] },
+        "feedback" => ->(p) { [ticket(p), required(p, "feedback")] },
+        "questions" => ->(_p) { [] },
+        "question" => ->(p) { [question_key(p), *question_flags(p)] },
+        # The key itself goes on stdin, so it's never in the command line or the panel.
+        "connect" => ->(p) { [Connections.find(required(p, "service")).name] }
+      }.merge(PLAN_ONLY.to_h { |name| [name, ->(p) { [plan(p)] }] }).freeze
+
+      module_function
+
+      def argv(action, params)
+        builder = BUILDERS[action.to_s] or raise ArgumentError, "the wizard can't run `#{action}`"
+        [action.to_s, *builder.call(params.to_h.transform_keys(&:to_s)), "--yes"]
+      end
+
+      # What `new` reads on stdin. The interview takes each answer up to an empty line, so blank
+      # lines inside an answer are folded away, and an empty answer is the empty line alone.
+      def interview_input(template, answers)
+        template.asked.map do |section|
+          answer = answers[section.key].to_s.strip.gsub(/\r\n?/, "\n").gsub(/\n\s*\n+/, "\n")
+          answer.empty? ? "\n" : "#{answer}\n\n"
+        end.join
+      end
+
+      def required(params, name)
+        params[name].to_s.strip.presence or raise ArgumentError, "#{name.tr("_", " ")} is required"
+      end
+
+      def plan(params)
+        key = required(params, "plan").upcase
+        raise ArgumentError, "not a plan key" unless key.match?(/\A[A-Z]+-\d+\z/)
+
+        key
+      end
+
+      def ticket(params)
+        "#{plan(params)}/#{ticket_key(required(params, "ticket"))}"
+      end
+
+      def ticket_key(key)
+        key.to_s.upcase.tap { |value| raise ArgumentError, "not a ticket key" unless value.match?(/\AT\d+\z/) }
+      end
+
+      def section(params)
+        key = required(params, "section")
+        PlanDriven.configuration.template[key] or raise ArgumentError, "unknown section #{key}"
+        key
+      end
+
+      def role(params)
+        params["role"].to_s.strip.empty? ? [] : ["--as", params["role"].strip]
+      end
+
+      def note(params)
+        params["note"].to_s.strip.empty? ? [] : ["--note", params["note"].strip]
+      end
+
+      def question_key(params)
+        required(params, "key").tap do |key|
+          raise ArgumentError, "not a question key" unless key.match?(Interview::KEY)
+        end
+      end
+
+      def question_flags(params)
+        return ["--remove"] if params["remove"].to_s == "1"
+
+        flags = []
+        flags += ["--title", params["title"].strip] if params["title"].to_s.strip != ""
+        flags += ["--ask", params["question"].strip] if params["question"].to_s.strip != ""
+        flags += ["--group", params["group"]] if params["group"].to_s != ""
+        flags << "--required" if params["required"].to_s == "1"
+        flags << "--optional" if params["required"].to_s == "0"
+        flags
+      end
+    end
+
+    # One command run: its output in a log file, its state in a JSON file next to it, so any
+    # request (and any Puma thread) can read how it's going.
+    class Job
+      # About as many characters as fit on a line of the terminal panel, for tables.
+      PANEL_COLUMNS = 76
+      SERVER_ENV = %w[RAILS_ENV RACK_ENV PORT PIDFILE].freeze
+
+      attr_reader :id
+
+      def self.dir(root = PlanDriven.configuration.root_path)
+        root.join("tmp/plan_driven/wizard").tap { |path| FileUtils.mkdir_p(path) }
+      end
+
+      def self.find(id, root: PlanDriven.configuration.root_path)
+        raise ArgumentError, "not a job" unless id.to_s.match?(/\A[a-f0-9]{16}\z/)
+
+        new(id, root: root).tap { |job| raise ArgumentError, "no job #{id}" unless job.state_file.exist? }
+      end
+
+      # Starts `argv` in a thread and returns at once.
+      def self.start(argv, stdin: nil, actor: nil, root: PlanDriven.configuration.root_path)
+        job = new(SecureRandom.hex(8), root: root)
+        job.begin!(argv, stdin: stdin, actor: actor)
+        job
+      end
+
+      def initialize(id, root:)
+        @id = id
+        @root = Pathname(root)
+      end
+
+      def begin!(argv, stdin:, actor:)
+        command = executable + argv
+        write_state("command" => display(command, actor), "status" => "running", "started_at" => Time.now.to_i)
+        File.write(log_file, "")
+        Thread.new { execute(command, stdin, actor) }
+      end
+
+      def state
+        JSON.parse(state_file.read)
+      end
+
+      def output
+        log_file.exist? ? log_file.read.force_encoding(Encoding::UTF_8).scrub : ""
+      end
+
+      def to_h
+        state.merge("id" => id, "output" => output)
+      end
+
+      def state_file
+        self.class.dir(@root).join("#{id}.json")
+      end
+
+      def log_file
+        self.class.dir(@root).join("#{id}.log")
+      end
+
+      private
+
+      def execute(command, stdin, actor)
+        env = { "LANG" => "en_US.UTF-8", "LC_ALL" => "en_US.UTF-8", "NO_COLOR" => "1", "COLUMNS" => PANEL_COLUMNS.to_s }
+        # The server's own environment stays with the server: a command runs as it would when typed.
+        SERVER_ENV.each { |name| env[name] = nil }
+        env["PLAN_DRIVEN_ACTOR"] = actor if actor.present?
+        status = Open3.popen2e(env, *command, chdir: @root.to_s) do |input, output, thread|
+          input.write(stdin.to_s)
+          input.close
+          File.open(log_file, "a") do |log|
+            output.each_char do |char|
+              log.write(char)
+              log.flush if char == "\n"
+            end
+          end
+          thread.value
+        end
+        finish(status.exitstatus)
+      rescue StandardError => e
+        File.write(log_file, "\n✗ #{e.message}\n", mode: "a")
+        finish(1)
+      end
+
+      def finish(code)
+        write_state(state.merge("status" => code.to_i.zero? ? "succeeded" : "failed", "exit" => code,
+                                "finished_at" => Time.now.to_i))
+      end
+
+      def write_state(data)
+        File.write(state_file, JSON.generate(data))
+      end
+
+      def executable
+        binstub = @root.join("bin/plan-driven")
+        binstub.exist? ? ["bin/plan-driven"] : %w[bundle exec plan-driven]
+      end
+
+      def display(command, actor)
+        prefix = actor.present? ? "PLAN_DRIVEN_ACTOR=#{Shellwords.escape(actor)} " : ""
+        shown = command.map { |arg| arg.start_with?(@root.to_s) ? arg.delete_prefix("#{@root}/") : arg }
+        prefix + Shellwords.join(shown)
+      end
+    end
+
+    # The wizard's pages, in order, and which ones a plan in a given phase has reached.
+    module Steps
+      ORDER = [
+        ["plan", "Plan", "Read it, edit or redraft any section, then submit"],
+        ["approve", "Approve", "Every role signs off on this revision"],
+        ["tickets", "Tickets", "Draft the tickets, steer them, approve them"],
+        ["agents", "Agents & PRs", "One agent and one pull request per ticket"],
+        ["finish", "Proof & report", "Evidence, the delivery report, tokens and cost"]
+      ].freeze
+
+      REACHED = {
+        "draft" => "plan", "in_review" => "approve", "approved" => "tickets", "ticketed" => "tickets",
+        "tickets_approved" => "agents", "in_development" => "agents", "delivered" => "finish"
+      }.freeze
+
+      module_function
+
+      def keys
+        ORDER.map(&:first)
+      end
+
+      def current(plan)
+        REACHED.fetch(plan.status, "plan")
+      end
+
+      def reached?(plan, step)
+        keys.index(step).to_i <= keys.index(current(plan)).to_i
+      end
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require "rails/engine"
+  require_relative "wizard/engine"
+end

data/lib/plan_driven.rb

@@ -12,6 +12,8 @@ require_relative "plan_driven/errors"
 require_relative "plan_driven/credentials"
 require_relative "plan_driven/configuration"
 require_relative "plan_driven/template"
+require_relative "plan_driven/interview"
+require_relative "plan_driven/connections"
 require_relative "plan_driven/schema_context"
 require_relative "plan_driven/workflow"
 require_relative "plan_driven/models"
@@ -26,10 +28,13 @@ require_relative "plan_driven/agent_prompt"
 require_relative "plan_driven/http"
 require_relative "plan_driven/github"
 require_relative "plan_driven/cursor_agents"
+require_relative "plan_driven/local_agents"
+require_relative "plan_driven/usage"
 require_relative "plan_driven/repository"
 require_relative "plan_driven/renderer"
 require_relative "plan_driven/evidence"
 require_relative "plan_driven/delivery"
+require_relative "plan_driven/wizard"
 require_relative "plan_driven/railtie" if defined?(Rails::Railtie)
 
 module PlanDriven

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plan_driven
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ivan Blažević
@@ -66,6 +66,21 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/controllers/plan_driven/wizard/application_controller.rb
+- app/controllers/plan_driven/wizard/configuration_controller.rb
+- app/controllers/plan_driven/wizard/jobs_controller.rb
+- app/controllers/plan_driven/wizard/plans_controller.rb
+- app/views/layouts/plan_driven/wizard/application.html.erb
+- app/views/plan_driven/wizard/configuration/show.html.erb
+- app/views/plan_driven/wizard/plans/_agents.html.erb
+- app/views/plan_driven/wizard/plans/_approve.html.erb
+- app/views/plan_driven/wizard/plans/_finish.html.erb
+- app/views/plan_driven/wizard/plans/_plan.html.erb
+- app/views/plan_driven/wizard/plans/_tickets.html.erb
+- app/views/plan_driven/wizard/plans/index.html.erb
+- app/views/plan_driven/wizard/plans/new.html.erb
+- app/views/plan_driven/wizard/plans/show.html.erb
+- config/routes.rb
 - exe/plan-driven
 - lib/generators/plan_driven/install_generator.rb
 - lib/generators/plan_driven/templates/create_plan_driven_tables.rb.tt
@@ -73,11 +88,13 @@ files:
 - lib/plan_driven.rb
 - lib/plan_driven/agent_prompt.rb
 - lib/plan_driven/cli.rb
+- lib/plan_driven/cli/config_commands.rb
 - lib/plan_driven/cli/plan_commands.rb
 - lib/plan_driven/cli/setup_commands.rb
 - lib/plan_driven/cli/ticket_commands.rb
 - lib/plan_driven/cli/ui.rb
 - lib/plan_driven/configuration.rb
+- lib/plan_driven/connections.rb
 - lib/plan_driven/credentials.rb
 - lib/plan_driven/cursor_agents.rb
 - lib/plan_driven/cursor_llm.mjs
@@ -95,8 +112,10 @@ files:
 - lib/plan_driven/guards/ticket_guard.rb
 - lib/plan_driven/guards/ticket_normalizer.rb
 - lib/plan_driven/http.rb
+- lib/plan_driven/interview.rb
 - lib/plan_driven/json_reply.rb
 - lib/plan_driven/llm.rb
+- lib/plan_driven/local_agents.rb
 - lib/plan_driven/models.rb
 - lib/plan_driven/models/approval.rb
 - lib/plan_driven/models/event.rb
@@ -114,7 +133,10 @@ files:
 - lib/plan_driven/schema_context.rb
 - lib/plan_driven/template.rb
 - lib/plan_driven/ticket_generator.rb
+- lib/plan_driven/usage.rb
 - lib/plan_driven/version.rb
+- lib/plan_driven/wizard.rb
+- lib/plan_driven/wizard/engine.rb
 - lib/plan_driven/workflow.rb
 homepage: https://github.com/blaz1988/plan-driven
 licenses: