@zalom/plastic 2.0.0-alpha.20 → 2.0.0-alpha.22

package/scripts/lib/session_usage.rb

@@ -0,0 +1,190 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+# SessionUsage (intent 355, D10): reads the harness transcripts modified since
+# a cutoff, dedupes assistant records by message id (the harness logs one
+# record per content block), and reports per session the model, the calls in
+# the window, the boot and last context, the median step, the steps over 5k,
+# and the cache read. Context is input plus cache read plus cache write.
+# Broken records are counted and named, never averaged over. The transcripts
+# root and the rate-limit cache path are injected; nothing reads ENV.
+class SessionUsage
+  WINDOW = 5 * 3600
+  BIG_STEP = 5_000
+  LABEL_WIDTH = 70
+  NO_PROMPT = "(no prompt)"
+  SYNTHETIC_MODEL = "<synthetic>"
+  CONTEXT_FIELDS = %w[input_tokens cache_read_input_tokens cache_creation_input_tokens].freeze
+  TRANSCRIPT_GLOBS = [File.join("*", "*.jsonl"), File.join("*", "*", "subagents", "*.jsonl")].freeze
+  HEADERS = ["session", "model", "calls", "boot", "last", "median step", "big steps", "cache read", "broken", "prompt"].freeze
+
+  def initialize(transcripts_root:, rate_limits_path:, now: Time.now)
+    @transcripts_root = transcripts_root
+    @rate_limits_path = rate_limits_path
+    @now = now
+  end
+
+  def cutoff(since: nil)
+    return [since, "since"] if since
+
+    reset = reset_time
+    return [reset - WINDOW, "rate-limit reset"] if reset && reset > @now
+
+    [@now - WINDOW, "last 5 hours"]
+  end
+
+  def report(since: nil)
+    at, source = cutoff(since: since)
+    header = { "status" => "ok", "root" => @transcripts_root, "cutoff" => at.getutc.iso8601, "cutoff_source" => source }
+    return header.merge("status" => "unavailable") unless File.directory?(@transcripts_root)
+
+    broken = []
+    sessions = transcripts(at).filter_map { |path| summarize(path, at, broken) }
+    header.merge("sessions" => sessions.sort_by { |s| -s["cache_read"] }, "broken" => broken)
+  end
+
+  def self.render_text(report)
+    return "Session usage: unavailable (no transcripts directory at #{report['root']})\n" if report["status"] == "unavailable"
+
+    out = +"Session usage since #{report['cutoff']} (#{report['cutoff_source']})\n\n"
+    out << (report["sessions"].empty? ? "(no sessions)\n" : table(report["sessions"]))
+    return out if report["broken"].empty?
+
+    out << "\nBroken records (#{report['broken'].size}):\n"
+    report["broken"].each { |b| out << "  #{b['file']}:#{b['line']}  #{b['error']}\n" }
+    out
+  end
+
+  def self.table(sessions)
+    rows = sessions.map do |s|
+      boot = tokens(s["boot"]) + (s["started_before_cutoff"] ? "*" : "")
+      [s["id"], s["model"].to_s, s["calls"].to_s, boot, tokens(s["last"]), tokens(s["median_step"]),
+       s["big_steps"].to_s, tokens(s["cache_read"]), s["broken"].to_s, s["label"]]
+    end
+    widths = HEADERS.each_index.map { |i| ([HEADERS] + rows).map { |r| r[i].length }.max }
+    lines = ([HEADERS] + rows).map { |r| r.each_with_index.map { |cell, i| cell.ljust(widths[i]) }.join("  ").rstrip }
+    note = sessions.any? { |s| s["started_before_cutoff"] } ? "\n* boot predates the cutoff\n" : ""
+    lines.join("\n") + "\n" + note
+  end
+
+  def self.tokens(count)
+    return "-" if count.nil?
+
+    count.abs >= 1_000 ? format("%.1fk", count / 1_000.0) : count.to_s
+  end
+
+  private_class_method :table, :tokens
+
+  private
+
+  def reset_time
+    return unless File.file?(@rate_limits_path)
+
+    value = JSON.parse(File.read(@rate_limits_path))["resets_at"].to_s
+    return if value.empty?
+
+    value.match?(/\A\d+\z/) ? Time.at(value.to_i).utc : Time.iso8601(value)
+  rescue JSON::ParserError, ArgumentError, TypeError
+    nil
+  end
+
+  def transcripts(cutoff)
+    TRANSCRIPT_GLOBS.flat_map { |glob| Dir.glob(File.join(@transcripts_root, glob)) }
+                    .select { |path| File.mtime(path) >= cutoff }
+                    .sort
+  end
+
+  def summarize(path, cutoff, broken)
+    calls = {}
+    label = nil
+    torn = 0
+    File.foreach(path).with_index(1) do |line, number|
+      next if line.strip.empty?
+
+      record = JSON.parse(line)
+      raise TypeError, "record is not a JSON object" unless record.is_a?(Hash)
+
+      label ||= prompt_line(record)
+      call = call_from(record)
+      next unless call
+
+      calls[call[:id]] = calls.key?(call[:id]) ? call.merge(at: calls[call[:id]][:at]) : call
+    rescue JSON::ParserError
+      torn += 1
+      broken << { "file" => path, "line" => number, "error" => "unparsable JSON" }
+    rescue ArgumentError, TypeError => e
+      torn += 1
+      broken << { "file" => path, "line" => number, "error" => e.message }
+    end
+    row(path, calls.values, cutoff, label, torn)
+  end
+
+  def row(path, calls, cutoff, label, torn)
+    window = calls.each_index.select { |i| calls[i][:at] >= cutoff }
+    return if window.empty? && torn.zero?
+
+    steps = window.filter_map { |i| calls[i][:context] - calls[i - 1][:context] if i.positive? }
+    {
+      "id" => File.basename(path, ".jsonl"),
+      "file" => path,
+      "label" => label || NO_PROMPT,
+      "model" => calls.last && calls.last[:model],
+      "calls" => window.size,
+      "boot" => calls.first && calls.first[:context],
+      "last" => calls.last && calls.last[:context],
+      "median_step" => median(steps),
+      "big_steps" => steps.count { |step| step > BIG_STEP },
+      "cache_read" => window.sum { |i| calls[i][:cache_read] },
+      "broken" => torn,
+      "started_before_cutoff" => !calls.empty? && calls.first[:at] < cutoff,
+    }
+  end
+
+  def call_from(record)
+    return unless record["type"] == "assistant"
+
+    message = record["message"]
+    raise TypeError, "assistant record without a message" unless message.is_a?(Hash)
+    return if message["model"] == SYNTHETIC_MODEL
+
+    usage = message["usage"]
+    raise ArgumentError, "assistant record without message id or usage" unless message["id"] && usage.is_a?(Hash)
+
+    {
+      id: message["id"],
+      model: message["model"],
+      at: Time.iso8601(record["timestamp"].to_s),
+      context: CONTEXT_FIELDS.sum { |field| usage[field].to_i },
+      cache_read: usage["cache_read_input_tokens"].to_i,
+    }
+  end
+
+  def prompt_line(record)
+    return unless record["type"] == "user" && !record["isMeta"]
+
+    text = prompt_text(record["message"].is_a?(Hash) ? record["message"]["content"] : nil)
+    return if text.nil?
+
+    first = text.lines.map(&:strip).find { |line| !line.empty? && !line.start_with?("<") }
+    first && first[0, LABEL_WIDTH]
+  end
+
+  def prompt_text(content)
+    return content if content.is_a?(String)
+    return unless content.is_a?(Array)
+
+    block = content.find { |b| b.is_a?(Hash) && b["type"] == "text" }
+    block && block["text"]
+  end
+
+  def median(values)
+    return if values.empty?
+
+    sorted = values.sort
+    middle = sorted.size / 2
+    sorted.size.odd? ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2
+  end
+end

package/scripts/meter-watch

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# meter-watch (intent 355, n5, D6): reads the rate-limit cache under --home
+# and writes ~/.plastic/.cache/meter-state.json with the state (ok, reduce,
+# stop, resume, stale, unavailable), the two raw percentages, the reset
+# time, and when it was checked. A session watches that one file instead of
+# every session parsing the cache and re-deriving the thresholds.
+#
+# Usage:
+#   meter-watch [--home DIR]
+#   meter-watch --install-timer [--home DIR]
+#
+# --install-timer writes a LaunchAgent plist under --home (default
+# ~/.plastic when --home is not given) that runs this tick every 20
+# minutes. It never calls launchctl; load it yourself with the command it
+# prints. The Plastic installer never calls --install-timer on its own.
+#
+# Exit codes: 0 reported (unavailable included); 2 usage error.
+
+require "json"
+require_relative "lib/meter_watch"
+
+def usage_abort(message)
+  warn "meter-watch: #{message}"
+  warn "Usage: meter-watch [--home DIR] [--install-timer]"
+  exit 2
+end
+
+home = File.join(Dir.home, ".plastic")
+install_timer = false
+
+argv = ARGV.dup
+until argv.empty?
+  case (token = argv.shift)
+  when "--home"
+    usage_abort("--home requires a value") if argv.empty?
+    home = argv.shift
+  when "--install-timer"
+    install_timer = true
+  else
+    usage_abort("unknown argument #{token.inspect}")
+  end
+end
+
+home = File.expand_path(home)
+
+if install_timer
+  plist_path = MeterWatch.install_timer(home: home, script_path: File.expand_path(__FILE__))
+  puts "Installed LaunchAgent at #{plist_path}"
+  puts "Run `launchctl load #{plist_path}` to activate it."
+  exit 0
+end
+
+state = MeterWatch.new(home: home).tick
+puts JSON.generate(state)

package/scripts/read-config

@@ -14,9 +14,9 @@ require_relative "lib/agent_models"
 DEFAULTS = {
   "version" => 3,
   "stale_threshold_days" => 3,
-  # Absolute token counts for a 1M window, 35 and 50 percent (intent 312, 296 D38).
-  "context_offer_tokens" => 350_000,
-  "context_insist_tokens" => 500_000,
+  # Absolute token counts for a 1M window, 15 and 25 percent (intent 355, n5, D7).
+  "context_offer_tokens" => 150_000,
+  "context_insist_tokens" => 250_000,
   "execution_mode" => "subagent-driven",
   "hash_length" => 6,
   "hash_algorithm" => "sha256-base36",

package/scripts/runner

@@ -5,6 +5,7 @@
 require_relative "lib/savepoint"
 require_relative "lib/ready_set"
 require_relative "lib/runner_core"
+require_relative "lib/runner_proposals"
 
 # runner - the one executable over the graph-ready loop's declared node graph
 # (intent 340, G7, n1). A subcommand table: the public verbs (step, status,
@@ -138,6 +139,10 @@ module Runner
       end
     end
 
+    graph = context.graph || {}
+    fixes = RunnerProposals.review_fix_count(graph[:edges] || {}, graph[:nodes] || {})
+    puts "review fixes: #{fixes} of #{RunnerProposals::REVIEW_FIX_CAP}"
+
     complete = RunnerCore.complete?(context)
     puts
     puts complete ? "complete" : "stalled"

package/scripts/session-usage

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# session-usage (intent 355, D10): read the harness transcripts since a cutoff
+# and report per session the model, calls, boot context, last context, median
+# step, steps over 5k, and cache read. Broken records are counted and named.
+#
+# Usage:
+#   session-usage [--since <iso8601>] [--format text|json] [--root <dir>] [--rate-limits <file>]
+#
+# Defaults: the root is ~/.claude/projects, the rate-limit cache is
+# ~/.plastic/.cache/rate-limits.json, and the cutoff is that cache's reset
+# time minus five hours, else the last five hours.
+#
+# Exit codes: 0 reported (unavailable included); 2 usage error.
+
+require "json"
+require "time"
+require_relative "lib/session_usage"
+
+FLAGS = %w[--since --format --root --rate-limits].freeze
+FORMATS = %w[text json].freeze
+
+def usage_abort(message)
+  warn "session-usage: #{message}"
+  warn "Usage: session-usage [--since <iso8601>] [--format text|json] [--root <dir>] [--rate-limits <file>]"
+  exit 2
+end
+
+def parse_args(argv)
+  usage_abort("every flag takes a value") if argv.length.odd?
+  opts = argv.each_slice(2).to_h
+  unknown = opts.keys - FLAGS
+  usage_abort("unknown flag #{unknown.first.inspect}") unless unknown.empty?
+  usage_abort("unknown format #{opts['--format'].inspect}") if opts["--format"] && !FORMATS.include?(opts["--format"])
+  opts
+end
+
+def parse_since(value)
+  value && Time.iso8601(value)
+rescue ArgumentError
+  usage_abort("--since #{value.inspect} is not an ISO 8601 time")
+end
+
+opts = parse_args(ARGV)
+usage = SessionUsage.new(
+  transcripts_root: File.expand_path(opts.fetch("--root", File.join(Dir.home, ".claude", "projects"))),
+  rate_limits_path: File.expand_path(opts.fetch("--rate-limits", File.join(Dir.home, ".plastic", ".cache", "rate-limits.json")))
+)
+report = usage.report(since: parse_since(opts["--since"]))
+if opts["--format"] == "json"
+  puts JSON.pretty_generate(report)
+else
+  print SessionUsage.render_text(report)
+end

package/scripts/skill-lint

@@ -2,11 +2,13 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# skill-lint: deterministic CLI over SkillLint (intent 85b).
+# skill-lint: deterministic CLI over SkillLint (intent 85b), plus one CLI-local
+# check (intent 341, G8, n1, C35).
 #
-# Runs the five structural skill checks (body-budget, frontmatter-validity,
-# bare-pointer, orphan-files, references-depth) over a directory of Agent
-# Skills and reports every violation. Mirrors `scripts/validate-intent`'s
+# Runs the five structural checks (body-budget, frontmatter-validity,
+# bare-pointer, orphan-files, references-depth) via SkillLint, then this
+# script's own refusal-restatement check, over a directory of Agent Skills,
+# and reports every violation. Mirrors `scripts/validate-intent`'s
 # CLI-over-lib shape and exit-code contract.
 #
 # Usage:
@@ -17,6 +19,112 @@
 
 require_relative "lib/skill_lint"
 
+# RefusalRestatementCheck (C35): a skill body must not restate, past a short
+# run of words, a refusal rule the conventions chapter already carries; it
+# must link that chapter instead. No-op when <skills_dir>/conventions/references
+# does not exist, so an older tree or a fixture dir with no conventions chapter
+# is unaffected.
+#
+# Deliberately lives in this CLI, not in scripts/lib/skill_lint.rb: C35 is a
+# doctrine-duplication check, one level removed from SkillLint's five
+# structural checks, and keeping it here means adding it touches only the
+# files this change is scoped to.
+class RefusalRestatementCheck
+  REFUSAL_KEYWORD_RE = /\brefus(e|es|ed|ing|al)\b/i
+  CONVENTIONS_LINK_RE = %r{conventions/references/|plastic-conventions}i
+
+  # How many consecutive normalized words must match, verbatim, between a
+  # skill's refusal paragraph and the doctrine text before it counts as a
+  # restatement rather than a coincidental shared phrase.
+  NGRAM = 6
+
+  def initialize(skills_dir)
+    @skills_dir = skills_dir
+  end
+
+  def run
+    doctrine = doctrine_blob
+    return [] unless doctrine
+
+    skill_md_paths.flat_map do |skill_md|
+      skill_dir = File.dirname(skill_md)
+      next [] if File.basename(skill_dir) == "conventions" # the source never restates itself
+
+      check_skill(skill_dir, skill_md, File.read(skill_md), doctrine)
+    end
+  end
+
+  private
+
+  def skill_md_paths
+    Dir.glob(File.join(@skills_dir, "*", "SKILL.md")).sort
+  end
+
+  def doctrine_blob
+    chapters = Dir.glob(File.join(@skills_dir, "conventions", "references", "*.md")).sort
+    return nil if chapters.empty?
+
+    text = chapters.map { |f| File.read(f) }.join(" ")
+    " #{normalize_words(text).join(" ")} "
+  end
+
+  def normalize_words(text)
+    text.downcase.gsub("`", "").gsub(/[^a-z0-9\s-]/, " ").split(/\s+/).reject(&:empty?)
+  end
+
+  # Same split as SkillLint's own frontmatter/body divide: `content.split("---", 3)`.
+  def body_and_offset(content)
+    parts = content.split("---", 3)
+    return [content, 0] if parts.length < 3
+
+    prefix_len = parts[0].length + 3 + parts[1].length + 3
+    [parts[2], content[0...prefix_len].count("\n")]
+  end
+
+  # Blank-line-delimited paragraph blocks, so a refusal keyword and its
+  # doctrine echo are compared across the whole paragraph, not one line.
+  def paragraph_blocks(lines)
+    blocks = []
+    start = nil
+    lines.each_with_index do |line, i|
+      if line.strip.empty?
+        blocks << { start: start, text: lines[start..(i - 1)].join } if start
+        start = nil
+      else
+        start ||= i
+      end
+    end
+    blocks << { start: start, text: lines[start..].join } if start
+    blocks
+  end
+
+  def restated?(block_text, doctrine)
+    words = normalize_words(block_text)
+    return false if words.length < NGRAM
+
+    (0..(words.length - NGRAM)).any? do |i|
+      doctrine.include?(" #{words[i, NGRAM].join(" ")} ")
+    end
+  end
+
+  def check_skill(skill_dir, skill_md, content, doctrine)
+    name = File.basename(skill_dir)
+    body, offset = body_and_offset(content)
+
+    paragraph_blocks(body.lines).filter_map do |block|
+      next unless block[:text].match?(REFUSAL_KEYWORD_RE)
+      next if block[:text].match?(CONVENTIONS_LINK_RE) # links the chapter instead of restating
+      next unless restated?(block[:text], doctrine)
+
+      {
+        check: "refusal-restatement", skill: name, file: skill_md, line: offset + block[:start] + 1,
+        message: "this paragraph restates a refusal rule word-for-word from " \
+                  "skills/conventions/references/; link the chapter instead of repeating its text",
+      }
+    end
+  end
+end
+
 def resolve_skills_dir(args)
   if (i = args.index("--skills-dir"))
     args[i + 1]
@@ -37,14 +145,15 @@ end
 
 dir = File.expand_path(resolve_skills_dir(ARGV))
 result = SkillLint.new(skills_dir: dir).run
+violations = result.violations + RefusalRestatementCheck.new(dir).run
 
-if result.ok?
+if violations.empty?
   puts "OK: #{dir}"
   exit 0
 end
 
 warn "VIOLATIONS: #{dir}"
-result.violations.each do |v|
+violations.each do |v|
   warn "#{v[:check]} #{v[:skill]} #{v[:file]}:#{v[:line].nil? ? "-" : v[:line]} #{v[:message]}"
 end
 exit 1