shaka 0.1.0.pre.1

data/skills/shaka/lib/shaka/claude_usage.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'response_count'
+
+module Shaka
+  # Reads Claude Code session transcripts (tested with 2.1.270 and 2.1.272), keeping only usage metadata.
+  class ClaudeUsage
+    include ResponseCount
+
+    HOST = 'Claude Code'
+    NOTE = 'Anthropic input excludes cached input and cache writes; reasoning output is part of output.'
+    LATEST_SCOPE = 'latest turn of the session, including its subagents; earlier turns excluded'
+
+    attr_reader :responses, :versions, :gaps
+
+    def self.discover
+      identity = ENV.fetch('CLAUDE_CODE_SESSION_ID', nil)
+      return [] unless identity&.match?(/\A[0-9a-f-]{36}\z/)
+
+      home = ENV.fetch('CLAUDE_CONFIG_DIR', File.expand_path('~/.claude'))
+      sessions = Dir.glob(File.join(home, 'projects', '*', "#{identity}.jsonl"))
+      return [] unless sessions.one? && session_of(sessions.first) == identity
+
+      sessions + Dir.glob(File.join(File.dirname(sessions.first), identity, 'subagents', '*.jsonl'))
+    end
+
+    def self.session_of(file)
+      File.foreach(file, encoding: 'UTF-8') do |line|
+        record = JSON.parse(line)
+        return record['sessionId'] if record.is_a?(Hash) && record.key?('sessionId')
+      rescue JSON::ParserError, EncodingError
+        next
+      end
+      nil
+    rescue SystemCallError
+      nil
+    end
+
+    private_class_method :session_of
+
+    def initialize(files, turns, all_turns: false)
+      @responses = {}
+      @versions = []
+      @gaps = []
+      sources = files.map { |file| read(file) }
+      records = sources.map(&:first).flat_map(&:values)
+      selected(records, wanted_turns(sources, turns), all_turns).each { |record| count(record) }
+    end
+
+    private
+
+    # Without explicit turns, every source uses the first source's latest turn.
+    def wanted_turns(sources, turns)
+      (turns.empty? ? [sources.dig(0, 1)] : turns).select { |turn| turn?(turn) }
+    end
+
+    # Every mode needs an identified turn, as in the Codex reader.
+    def selected(records, wanted, all_turns)
+      identified = records.select { |record| turn?(record['turn_id']) }
+      unreadable if all_turns && identified.size < records.size
+      all_turns ? identified : identified.select { |record| wanted.include?(record['turn_id']) }
+    end
+
+    def turn?(turn)
+      turn.is_a?(String) && !turn.strip.empty?
+    end
+
+    # Streamed lines repeat a response; the last line carries its final usage.
+    def read(file)
+      records = {}
+      turn = nil
+      File.foreach(file, encoding: 'UTF-8') do |line|
+        record = parse(line)
+        turn = record['promptId'] if record['type'] == 'user'
+        records.merge!(response(record, turn)) if record['type'] == 'assistant'
+      end
+      [records, turn]
+    rescue SystemCallError
+      [unreadable, nil]
+    end
+
+    def response(record, turn)
+      message = record['message'].is_a?(Hash) ? record['message'] : {}
+      @versions << record['version'] if record['version'].is_a?(String)
+      { message['id'] => { 'response_id' => message['id'], 'turn_id' => turn, 'timestamp' => record['timestamp'],
+                           'configuration' => ['anthropic', 'UNKNOWN', message['model'], record['effort']],
+                           'usage' => tokens(message['usage']) } }
+    end
+
+    def tokens(usage)
+      return {} unless usage.is_a?(Hash)
+
+      details = usage['output_tokens_details']
+      { 'input_tokens' => usage['input_tokens'], 'cached_input_tokens' => usage['cache_read_input_tokens'],
+        'output_tokens' => usage['output_tokens'], 'cache_write_input_tokens' => usage['cache_creation_input_tokens'],
+        'reasoning_output_tokens' => (details['thinking_tokens'] if details.is_a?(Hash)) }
+    end
+
+    def parse(line)
+      record = JSON.parse(line)
+      record.is_a?(Hash) ? record : unreadable
+    rescue JSON::ParserError, EncodingError
+      unreadable
+    end
+
+    def unreadable
+      @gaps << 'Unreadable or unidentifiable records'
+      {}
+    end
+  end
+end

data/skills/shaka/lib/shaka/cost_estimate.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Shaka
+  # Prices configured-model scenarios from disjoint per-response token categories.
+  class CostEstimate
+    VERIFIED = '2026-09-15'
+    THRESHOLD = 272_000
+    RATES = {
+      'gpt-5.6-terra' => { credits: %w[50 5 300], api: %w[2 0.2 12] },
+      'gpt-5.6-sol' => { credits: %w[100 10 500], api: %w[4 0.4 20] },
+      'gpt-6-astra' => { credits: %w[250 25 1250], api: %w[10 1 50] }
+    }.freeze
+
+    def initialize(responses)
+      @responses = responses
+    end
+
+    def report
+      reasons = []
+      rows = @responses.group_by { |record| record['configuration'] }.map do |configuration, group|
+        row(configuration, group, reasons)
+      end.join("\n")
+      rows = '| UNKNOWN | UNKNOWN | UNKNOWN | UNKNOWN | UNKNOWN |' if rows.empty?
+      markdown(rows, reasons)
+    end
+
+    private
+
+    def row(configuration, group, reasons)
+      credits, credit_reason = total(group, :credits)
+      api, api_reason = total(group, :api)
+      reasons.concat([credit_reason, api_reason].compact)
+      provider, model, _, effort = configuration
+      "| #{[safe(provider), safe(model), safe(effort), show(credits, 'credits'), show(api, '$')].join(' | ')} |"
+    end
+
+    def markdown(rows, reasons)
+      <<~MARKDOWN
+
+        Cost estimates are PARTIAL configured-model scenarios for the selected native responses.
+        Actual charge: UNKNOWN (routed model, billing mode, service tier, account terms, and external work unavailable).
+
+        <details>
+        <summary>Cost scenarios</summary>
+
+        Standard Codex credit and Standard OpenAI API-equivalent rates verified #{VERIFIED};
+        historical rates and account-specific terms may differ. Effort has no price multiplier.
+        Cached input and reasoning output are subsets, not extra charges. API cache writes
+        are included in input; Codex credit cache-write pricing is unavailable.
+        The API scenario applies each request's 272K context threshold before summing.
+
+        | Provider | Configured model | Effort | Codex credits estimate | API-equivalent USD estimate |
+        | --- | --- | --- | ---: | ---: |
+        #{rows}
+
+        #{reasons.uniq.join('; ')}
+        Sources: [Codex credit rates](https://learn.chatgpt.com/docs/pricing#token-rates),
+        API prices for [Terra](https://developers.openai.com/api/docs/models/gpt-5.6-terra),
+        [Sol](https://developers.openai.com/api/docs/models/gpt-5.6-sol), and
+        [Astra](https://developers.openai.com/api/docs/models/gpt-6-astra),
+        [prompt-cache accounting](https://developers.openai.com/api/docs/guides/prompt-caching).
+
+        </details>
+      MARKDOWN
+    end
+
+    def total(group, mode)
+      amounts = group.map { |record| price(record, mode) }
+      reason = amounts.map(&:last).compact.first
+      [reason ? nil : amounts.sum { |amount, _| amount }, reason]
+    end
+
+    def price(record, mode)
+      provider, model = record['configuration']
+      rate = RATES.dig(model, mode) if provider == 'openai'
+      return [nil, 'Unsupported provider or configured model'] unless rate
+
+      tokens, reason = categories(record['usage'])
+      return [nil, reason] if reason
+      return [nil, 'Credit cache-write rate UNKNOWN'] if mode == :credits && tokens[2].positive?
+
+      [bill(tokens, rate, mode) / 1_000_000, nil]
+    end
+
+    def categories(usage)
+      return [nil, 'Incomplete billable token categories'] unless usage.is_a?(Hash)
+
+      tokens = %w[input_tokens cached_input_tokens cache_write_input_tokens output_tokens].map { |field| usage[field] }
+      return [nil, 'Incomplete billable token categories'] unless valid_counters?(tokens)
+
+      input, cached, writes, output = tokens
+      reasoning = usage['reasoning_output_tokens']
+      return [nil, 'Inconsistent token subsets'] if cached + writes > input || invalid_reasoning?(reasoning, output)
+
+      [tokens, nil]
+    end
+
+    def bill(tokens, rate, mode)
+      large = mode == :api && tokens[0] > THRESHOLD
+      (input_bill(tokens, rate, mode) * (large ? 2 : 1)) +
+        (tokens[3] * Rational(rate[2]) * (large ? Rational(3, 2) : 1))
+    end
+
+    def input_bill(tokens, rate, mode)
+      input, cached, writes = tokens
+      input_rate, cached_rate = rate.first(2).map { |value| Rational(value) }
+      amount = ((input - cached - writes) * input_rate) + (cached * cached_rate)
+      mode == :api ? amount + (writes * input_rate * Rational(5, 4)) : amount
+    end
+
+    def valid_counters?(tokens)
+      tokens.all? { |value| value.is_a?(Integer) && value >= 0 }
+    end
+
+    def invalid_reasoning?(reasoning, output)
+      reasoning.is_a?(Integer) && (reasoning.negative? || reasoning > output)
+    end
+
+    def show(amount, unit)
+      return 'UNKNOWN' unless amount
+
+      formatted = format('%.6f', amount)
+      unit == '$' ? "#{unit}#{formatted}" : "#{formatted} #{unit}"
+    end
+
+    def safe(value)
+      value.is_a?(String) && value.match?(/\A[a-zA-Z0-9][a-zA-Z0-9._:-]{0,79}\z/) ? value : 'UNKNOWN'
+    end
+  end
+end

data/skills/shaka/lib/shaka/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Shaka
+  # An actionable failure at the workflow boundary.
+  class Error < StandardError; end
+end

data/skills/shaka/lib/shaka/github.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require_relative 'error'
+require_relative 'publishing'
+
+module Shaka
+  # The native pull-request evidence a publication decision depends on.
+  SNAPSHOT_QUERY = <<~GRAPHQL
+    query($owner: String!, $name: String!, $number: Int!) {
+      repository(owner: $owner, name: $name) {
+        pullRequest(number: $number) {
+          id number url state isDraft headRefOid baseRefName
+          mergeStateStatus reviewDecision viewerCanMergeAsAdmin
+          isInMergeQueue isMergeQueueEnabled autoMergeRequest { enabledAt }
+          headRepository { nameWithOwner } baseRepository { nameWithOwner }
+        }
+      }
+    }
+  GRAPHQL
+
+  # Reads native PR evidence and publishes reviews bound to its current commit.
+  class GitHub
+    include Publishing
+
+    def initialize(repository, number, runner: nil)
+      unless repository.is_a?(String) && repository.ascii_only? &&
+             repository.match?(%r{\A[\w-]+/(?!\.{1,2}\z)[\w.-]+\z})
+        raise Error, 'Expected a GitHub repository in OWNER/REPO form.'
+      end
+
+      @repository = repository
+      @number = positive_integer(number)
+      @runner = runner || ->(argv, stdin_data:) { Open3.capture3(*argv, stdin_data: stdin_data) }
+    end
+
+    def snapshot
+      owner, name = @repository.split('/')
+      repository = graphql(SNAPSHOT_QUERY, owner: owner, name: name, number: @number)['repository']
+      result = repository['pullRequest'] if repository.is_a?(Hash)
+      raise Error, 'GitHub did not return the requested pull request.' unless result.is_a?(Hash)
+
+      result
+    end
+
+    def required_checks
+      result = execute(['gh', 'pr', 'checks', @number.to_s, '--repo', @repository,
+                        '--required', '--json', 'name,state,bucket,link'], accepted: [0, 1, 8])
+      raise Error, 'GitHub required checks response must be an array.' unless result.is_a?(Array)
+
+      result
+    rescue Error
+      raise Error, 'Required-check evidence is unavailable; confirm native required checks and GitHub access.'
+    end
+
+    def review(id)
+      api("#{reviews_path}/#{positive_integer(id)}")
+    end
+
+    def walkthrough(head:, body:)
+      body = utf8(body)
+      raise Error, 'Walkthrough body must be nonempty.' if body.strip.empty?
+
+      verify_head(head)
+      verify_rendering(body)
+      created = api(reviews_path, method: 'POST', fields: { event: 'COMMENT', commit_id: head, body: body })
+      published = review(created['id'])
+      verify_review(published, created['id'], head, body)
+      verify_head(head, review_id: created['id'])
+      published
+    end
+
+    def api(path, method: 'GET', fields: {})
+      result = execute(['gh', 'api', path, '--method', method, '--input', '-'], input: JSON.generate(fields))
+      raise Error, 'GitHub API response must be an object.' unless result.is_a?(Hash)
+
+      result
+    end
+
+    def graphql(query, variables = {})
+      response = api('graphql', method: 'POST', fields: { query: query, variables: variables })
+      raise Error, 'GraphQL failed or returned missing data.' if response['errors'] || !response['data'].is_a?(Hash)
+
+      response['data']
+    end
+
+    private
+
+    def positive_integer(value)
+      unless value.to_s.ascii_only? && value.to_s.match?(/\A[1-9]\d*\z/)
+        raise Error, 'Expected a positive integer identifier.'
+      end
+
+      value.to_i
+    end
+
+    def reviews_path
+      "repos/#{@repository}/pulls/#{@number}/reviews"
+    end
+
+    def verify_head(head, review_id: nil)
+      raise Error, 'Expected a full commit SHA.' unless head.is_a?(String) && head.match?(/\A[0-9a-f]{40}\z/)
+
+      pr = snapshot
+      return if pr['state'] == 'OPEN' && pr['headRefOid'] == head
+
+      detail = review_id ? " Review #{review_id} was created; inspect the PR before retrying." : ''
+      raise Error, "Pull request is not open at the expected head.#{detail}"
+    end
+
+    def verify_review(review, id, head, body)
+      return if review.values_at('id', 'state', 'commit_id', 'body') == [id, 'COMMENTED', head, body]
+
+      raise Error, 'Published walkthrough review did not match its commit, body, or COMMENT state.'
+    end
+
+    def execute(argv, input: '', accepted: [0]) = parse_json(capture(argv, input: input, accepted: accepted))
+
+    def capture(argv, input: '', accepted: [0])
+      stdout, _stderr, status = @runner.call(argv, stdin_data: input)
+      unless accepted.include?(status.exitstatus)
+        raise Error, "gh #{argv[1, 2].join(' ')} failed (exit #{status.exitstatus})."
+      end
+
+      utf8(stdout)
+    rescue Errno::ENOENT
+      raise Error, 'GitHub CLI is unavailable; install gh and authenticate.'
+    end
+
+    def parse_json(output)
+      JSON.parse(utf8(output))
+    rescue JSON::ParserError
+      raise Error, 'GitHub returned invalid JSON.'
+    end
+
+    def utf8(value)
+      raise Error, 'Expected UTF-8 text.' unless value.is_a?(String)
+
+      text = value.dup.force_encoding(Encoding::UTF_8)
+      raise Error, 'Invalid UTF-8 text.' unless text.valid_encoding?
+
+      text
+    end
+  end
+end

data/skills/shaka/lib/shaka/merge.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Shaka
+  # Applies native GitHub gates; the calling skill must establish merge authority.
+  class Merge
+    MUTATION = <<~GRAPHQL
+      mutation($id: ID!, $head: GitObjectID!) {
+        mergePullRequest(input: {pullRequestId: $id, expectedHeadOid: $head, mergeMethod: SQUASH}) {
+          pullRequest { state headRefOid merged mergeCommit { oid } }
+        }
+      }
+    GRAPHQL
+
+    def initialize(github)
+      @github = github
+    end
+
+    def call(head:, walkthrough:)
+      raise Error, 'Expected a full commit SHA' unless head.is_a?(String) && head.match?(/\A[0-9a-f]{40}\z/)
+
+      verify_snapshot(@github.snapshot, head)
+      verify_checks(@github.required_checks)
+      verify_walkthrough(@github.review(walkthrough), head, walkthrough)
+      current = @github.snapshot
+      verify_snapshot(current, head)
+      submit(current.fetch('id'), head)
+    end
+
+    private
+
+    def verify_snapshot(pull, head)
+      raise Error, 'PR head changed; refresh verification and walkthrough' unless pull['headRefOid'] == head
+      raise Error, 'PR must be open and not a draft' unless pull['state'] == 'OPEN' && pull['isDraft'] == false
+      raise Error, 'GitHub PR identity is missing' unless pull['id'].is_a?(String) && !pull['id'].empty?
+
+      verify_submission_mode(pull)
+      verify_native_state(pull)
+    end
+
+    def verify_submission_mode(pull)
+      raise Error, 'Native protection must be enforced for this actor' unless pull['viewerCanMergeAsAdmin'] == false
+      unless pull['isMergeQueueEnabled'] == false && pull['isInMergeQueue'] == false
+        raise Error, 'Merge queues are unsupported by this pilot'
+      end
+      return if pull.key?('autoMergeRequest') && pull['autoMergeRequest'].nil?
+
+      raise Error, 'Existing or unknown delayed auto-merge blocks immediate merge'
+    end
+
+    def verify_native_state(pull)
+      unless pull['mergeStateStatus'] == 'CLEAN'
+        raise Error, "GitHub merge state is not CLEAN: #{pull['mergeStateStatus'].inspect}"
+      end
+      return if pull.key?('reviewDecision') && [nil, 'APPROVED'].include?(pull['reviewDecision'])
+
+      raise Error, 'Required reviews are not satisfied or their state is unknown'
+    end
+
+    def verify_checks(checks)
+      unless checks.is_a?(Array) && !checks.empty?
+        raise Error, 'No observable required checks; native readiness is unknown'
+      end
+
+      checks.each do |check|
+        next if passing_check?(check)
+
+        raise Error, "Required check is not passing or is malformed: #{check.inspect}"
+      end
+    end
+
+    def passing_check?(check)
+      return false unless check.is_a?(Hash) && check['name'].is_a?(String) && !check['name'].strip.empty?
+
+      case check['state']
+      when 'SUCCESS' then check['bucket'] == 'pass'
+      when 'NEUTRAL', 'SKIPPED' then check['bucket'] == 'skipping'
+      else false
+      end
+    end
+
+    def verify_walkthrough(review, head, id)
+      unless review.is_a?(Hash) && review['id'].to_s == id.to_s && review['commit_id'] == head
+        raise Error, 'Walkthrough must identify a review on this PR at the expected head'
+      end
+      return if review['state'] == 'COMMENTED' && review['body'].is_a?(String) && !review['body'].strip.empty?
+
+      raise Error, 'Walkthrough must be a submitted COMMENT review with a nonempty body'
+    end
+
+    def submit(id, head)
+      result = @github.graphql(MUTATION, { 'id' => id, 'head' => head })
+      payload = result['mergePullRequest']
+      pr = payload['pullRequest'] if payload.is_a?(Hash)
+      unless pr.is_a?(Hash) && pr['merged'] == true && pr['state'] == 'MERGED' && pr['headRefOid'] == head
+        raise Error, 'GitHub did not confirm merging the expected head'
+      end
+
+      pr
+    rescue Error => e
+      raise Error, "#{e.message}; inspect live PR state before retrying a merge"
+    end
+  end
+end

data/skills/shaka/lib/shaka/publication.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Shaka
+  # Checks supplied text for the mechanical failures models reproduce by hand.
+  module PublicationText
+    ESCAPE = /\\[nrt]/
+    IDENTITY_FIELDS = %w[agent provider model effort].freeze
+
+    module_function
+
+    def required(value, field)
+      raise Error, "Publication #{field} must be nonempty text." unless value.is_a?(String) && !value.strip.empty?
+
+      checked(value, field)
+    end
+
+    # Fenced blocks and code spans hold intentional examples; only prose is checked.
+    def prose(text)
+      text.gsub(/^~~~.*?^~~~/m, '').gsub(/```.*?```/m, '').gsub(/(`+)[^`]*\1/, '')
+    end
+
+    # A summary is interpolated into raw HTML, so it must not be able to close its own tag.
+    def summary_text(value, field)
+      single_line(value, field).gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+    end
+
+    def list(value, field)
+      return [] if value.nil?
+      raise Error, "Publication #{field} must be a list." unless value.is_a?(Array)
+
+      value
+    end
+
+    def single_line(value, field)
+      text = required(value, field)
+      raise Error, "Publication #{field} must be a single line." if text.match?(/[\r\n]/)
+
+      text
+    end
+
+    def checked(value, field)
+      return value unless prose(value).match?(ESCAPE)
+
+      raise Error, "Publication #{field} contains a literal escape sequence; supply real line breaks."
+    end
+
+    def identity(value)
+      raise Error, 'Publication identity must be supplied.' unless value.is_a?(Hash)
+
+      fields = IDENTITY_FIELDS.map do |field|
+        text = value[field]
+        text.is_a?(String) && !text.strip.empty? ? single_line(text.strip, "identity #{field}") : 'UNKNOWN'
+      end
+      "🤖 #{fields.join(' · ')}"
+    end
+  end
+
+  # Renders the publication surfaces so headings, spacing, tables and details are Ruby's.
+  class Publication
+    def self.description(content) = new(content).render(%i[sections table details])
+    def self.comment(content) = new(content).render([])
+    def self.walkthrough(content) = new(content).render(%i[sections table details revision])
+
+    def initialize(content)
+      raise Error, 'Publication content must be an object.' unless content.is_a?(Hash)
+
+      @content = content
+    end
+
+    def render(parts)
+      blocks = [PublicationText.identity(@content['identity']),
+                PublicationText.required(@content['summary'], 'summary')]
+      parts.each { |part| blocks.concat(send(part)) }
+      "#{blocks.join("\n\n")}\n"
+    end
+
+    private
+
+    def sections
+      PublicationText.list(@content['sections'], 'sections').map do |section|
+        heading = PublicationText.single_line(section['heading'], 'section heading')
+        "## #{heading}\n\n#{PublicationText.required(section['body'], "section #{heading}")}"
+      end
+    end
+
+    def table
+      spec = @content['table']
+      return [] if spec.nil?
+
+      columns = table_columns(spec)
+      rows = PublicationText.list(spec['rows'], 'table rows').map { |row| table_row(row, columns.size) }
+      [[table_line(columns), table_line(['---'] * columns.size), *rows].join("\n")]
+    end
+
+    def table_columns(spec)
+      columns = spec.is_a?(Hash) ? PublicationText.list(spec['columns'], 'table columns') : []
+      raise Error, 'Publication table must define at least one column.' if columns.empty?
+
+      columns.map { |column| PublicationText.single_line(column, 'table column') }
+    end
+
+    def table_row(row, width)
+      cells = PublicationText.list(row, 'table row')
+      raise Error, "Publication table row has #{cells.size} cells; #{width} columns are defined." if cells.size != width
+
+      table_line(cells.map { |cell| PublicationText.single_line(cell.to_s, 'table cell') })
+    end
+
+    # Escaping pipes keeps a cell from silently adding a column.
+    def table_line(cells) = "| #{cells.map { |cell| cell.gsub('|', '\\|') }.join(' | ')} |"
+
+    def details
+      PublicationText.list(@content['details'], 'details').map do |detail|
+        summary = PublicationText.summary_text(detail['summary'], 'details summary')
+        body = PublicationText.required(detail['body'], "details #{summary}")
+        "<details>\n<summary>#{summary}</summary>\n\n#{body}\n\n</details>"
+      end
+    end
+
+    def revision
+      head = @content['head']
+      raise Error, 'Walkthrough requires the full commit SHA it explains.' unless head.to_s.match?(/\A[0-9a-f]{40}\z/)
+
+      ["_Walkthrough for commit `#{head}`. This is a COMMENT, not an approval._"]
+    end
+  end
+end