hecks 6.0.0 → 7.0.0

data/lib/hecks/storehouse/callers.rb

@@ -21,6 +21,7 @@ module Hecks
       def validate_caller_fields!(request)
         require_summary!(request.summary)
         valid_source!(request.source)
+        valid_surface!(request.surface)
         valid_caller!(request.role, request.actor_id)
       end
 
@@ -33,6 +34,13 @@ module Hecks
               "a one-line summary: is required on dispatch/query/state — it is what makes an audit row legible later"
       end
 
+      # :nodoc:
+      def valid_surface!(surface)
+        return if surface.nil? || SURFACES.include?(surface.to_s)
+
+        raise Runtime::TypeMismatch, "surface: #{surface.inspect} is not one of #{SURFACES.join(", ")}"
+      end
+
       # :nodoc:
       def valid_source!(source)
         return if source.nil? || SOURCE_TAGS.include?(source.to_s)

data/lib/hecks/storehouse/dispatching.rb

@@ -24,7 +24,7 @@ module Hecks
       # :nodoc:
       def perform_dispatch(request)
         validate_caller_fields!(request)
-        spec = resolve!(cli_for(request.bluebook), request.name, asking: false)
+        spec = resolve!(cli_for(request.runtime, request.bluebook), request.name, asking: false)
         require_caller_for_role_gated!(spec, request.role)
         envelope = command_envelope(request.args, spec)
 
@@ -95,7 +95,7 @@ module Hecks
       # @param names [Array<String>] short or qualified command names
       # @return [Array<String>] one line per name that resolves, in order
       def command_guide(runtime, names)
-        cli = cli_for(bluebook_for(runtime))
+        cli = cli_for(runtime, bluebook_for(runtime))
         names.filter_map do |name|
           guide_line(name, resolve!(cli, name.to_s, asking: false))
         rescue Runtime::NotFound
@@ -103,6 +103,17 @@ module Hecks
         end
       end
 
+      # The commands an agent may dispatch: those that explicitly declare `:agent` in their
+      # `audience`. A command that declares no audience is not an agent tool, so the default
+      # never grants agent access.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @return [Array<String>] the command names as the launcher lists them, in order
+      def agent_commands(runtime)
+        cli = cli_for(runtime, bluebook_for(runtime))
+        cli[:commands].filter_map { |name, spec| name.to_s if Array(spec[:audience]).include?("agent") }
+      end
+
       # :nodoc:
       def guide_line(name, spec)
         arguments = spec[:arguments].map { |arg| arg[:path].split(".").first + (arg[:required] ? "*" : "") }
@@ -131,7 +142,7 @@ module Hecks
       # @return [Hash] :ok (true only if every step's own :ok was true), :results
       # @raise [ArgumentError] for any other keyword
       def dispatch_batch(runtime:, steps:, summary:, **options)
-        check_options!(options, %i[source role actor_id])
+        check_options!(options, %i[source role actor_id surface])
         run_batch(runtime, steps, summary, options)
       end
 

data/lib/hecks/storehouse/identity.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Storehouse
+    # The ids a call used, named in its result: the record it addressed, and the references its arguments
+    # named. Extended onto `Storehouse`.
+    module Identity
+      # The arguments that name an id a call used: a run key, an earlier run it refers to, and the checkout
+      # and branch it resolved to.
+      IDENTITY_KEYS = %i[run from checkout branch].freeze
+
+      # The ids a call used: the record it addressed, and the references its arguments named, each unwrapped
+      # to its value. Absent ones are left out.
+      # :nodoc:
+      def ids_of(request, outcome)
+        ids = values_of(request)
+        ids[:id] = outcome[:id]
+        ids.compact
+      end
+
+      # The named arguments of a call, each reduced to its value.
+      # :nodoc:
+      def values_of(request)
+        named_arguments(request).transform_values { |field| value_of(field) }
+      end
+
+      # The arguments of a call that name an id, keyed by symbol.
+      # :nodoc:
+      def named_arguments(request)
+        symbolic = request.args.to_h.transform_keys(&:to_sym)
+        symbolic.slice(*IDENTITY_KEYS)
+      end
+
+      # A stored or caller-supplied field is its value, or the `{value:}` wrapper a word carries.
+      # :nodoc:
+      def value_of(field)
+        return field unless field.is_a?(Hash)
+
+        field.transform_keys(&:to_sym)[:value]
+      end
+    end
+  end
+end

data/lib/hecks/storehouse/querying.rb

@@ -15,7 +15,7 @@ module Hecks
       # @return [Hash] :ok and :rows (each JSON-safe); or the refused shape
       # @raise [ArgumentError] for any other keyword
       def query(runtime:, question:, summary:, args: {}, **options)
-        check_options!(options, %i[source role actor_id])
+        check_options!(options, %i[source role actor_id surface])
         request = Request.new(runtime: runtime, name: question, summary: summary, args: args, **options)
         request.bluebook, request.name = bluebook_and_name(runtime, question)
         audited(request, "query") { perform_query(request) }
@@ -24,7 +24,7 @@ module Hecks
       # :nodoc:
       def perform_query(request)
         validate_caller_fields!(request)
-        spec = resolve!(cli_for(request.bluebook), request.name, asking: true)
+        spec = resolve!(cli_for(request.runtime, request.bluebook), request.name, asking: true)
         rows = with_caller(request.role, request.actor_id) { answer(request, spec) }
 
         ok(summary: request.summary, rows: rows.map do |row|
@@ -46,16 +46,16 @@ module Hecks
       # @param id [String, Object, nil] one record's identity, or nil for every record
       # @param source [String, Symbol, nil] a SOURCE_TAGS tag naming who is calling
       # @return [Hash] :ok and, with id:, :record; without it, :count/:records; or refused
-      def state(runtime:, aggregate:, summary:, id: nil, source: nil)
+      def state(runtime:, aggregate:, summary:, id: nil, **tags)
         bluebook = bluebook_for(runtime)
         outcome  = perform_state(runtime, bluebook, aggregate, summary, id)
 
-        record!(bluebook.name, tool: "state", summary: summary, source: source, outcome: outcome)
-        outcome
+        record!(bluebook.name, tool: "state", summary: summary, **tags.slice(:source, :surface), outcome: outcome)
+        outcome.merge(ids: { id: id }.compact)
       rescue *refusal_classes => e
         outcome = refused(e, summary: summary)
-        record!(bluebook&.name, tool: "state", summary: summary, source: source, outcome: outcome)
-        outcome
+        record!(bluebook&.name, tool: "state", summary: summary, **tags.slice(:source, :surface), outcome: outcome)
+        outcome.merge(ids: { id: id }.compact)
       end
 
       # :nodoc:

data/lib/hecks/storehouse.rb

@@ -10,6 +10,7 @@ require_relative "projector"
 require_relative "runtime/errors"
 require_relative "storehouse/callers"
 require_relative "storehouse/audit"
+require_relative "storehouse/identity"
 require_relative "storehouse/dispatching"
 require_relative "storehouse/querying"
 require_relative "storehouse/introspection"
@@ -27,6 +28,10 @@ module Hecks
     # than guessed.
     SOURCE_TAGS = %w[process-manager operator hook sidequest-agent cascade daemon].freeze
 
+    # Which surface a call came in through, so the audit line says what made it: a person at a shell
+    # (`cli`), an agent over the MCP server (`mcp`), or the domain itself (`policy`, `saga`, `reaction`).
+    SURFACES = %w[cli mcp policy saga reaction].freeze
+
     # The root every domain path resolves under; HECKS_STOREHOUSE_ROOT widens it.
     # Hecks.boot Kernel.loads Ruby files here, so an unconfined path is
     # arbitrary code execution, not just a wrong-directory mistake.
@@ -34,10 +39,14 @@ module Hecks
 
     # One dispatch or query call: the booted domain, what it is asked, and who is asking.
     Request = Struct.new(:runtime, :bluebook, :name, :summary, :args, :source, :dry_run, :role, :actor_id,
-                         keyword_init: true)
+                         :surface, keyword_init: true) do
+      # @return [String, nil] the name of the bluebook the call asks, or nil when none is booted
+      def bluebook_name = bluebook&.name
+    end
 
     extend Callers
     extend Audit
+    extend Identity
     extend Dispatching
     extend Querying
     extend Introspection
@@ -80,7 +89,11 @@ module Hecks
 
     # The alias table CliRunner resolves against, for one bluebook.
     # :nodoc:
-    def cli_for(bluebook) = Projector.call(:cli, bluebook: bluebook, options: { program: "mcp" })
+    def cli_for(runtime, bluebook)
+      launcher = Adapters::Driving::LauncherOptions.settings(runtime, bluebook.name)
+      options = Adapters::Driving::LauncherOptions.projection(launcher, "mcp")
+      Projector.call(:cli, bluebook: bluebook, options: options)
+    end
 
     # The same alias table CliRunner resolves against, kept here so dispatch
     # and query never drift from what a human typing hecks run sees.
@@ -116,7 +129,7 @@ module Hecks
     # @param names [Array<String, nil>] short or qualified command names
     # @return [Array<String, nil>] one verb or nil per name, in order
     def verbs_for(runtime, names)
-      cli = cli_for(bluebook_for(runtime))
+      cli = cli_for(runtime, bluebook_for(runtime))
       names.map do |name|
         resolve!(cli, name.to_s, asking: false)[:command]
       rescue Runtime::NotFound
@@ -132,19 +145,24 @@ module Hecks
     # @yieldreturn [Hash] the call's outcome
     # :nodoc:
     def audited(request, tool)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       outcome = yield
-      bluebook = request.bluebook
-      record!(bluebook.name, tool: tool, verb: outcome[:verb], outcome: outcome, **audit_fields(request))
-      outcome.except(:verb)
+      record_call!(request, tool, started, verb: outcome[:verb], outcome: outcome)
+      outcome.except(:verb).merge(ids: ids_of(request, outcome))
     rescue *refusal_classes => e
       outcome = refused(e, summary: request.summary)
-      asked_of = request.bluebook
-      record!(asked_of&.name, tool: tool, outcome: outcome, **audit_fields(request))
-      outcome
+      record_call!(request, tool, started, outcome: outcome, refusal: refusal_kind(e))
+      outcome.merge(ids: ids_of(request, outcome))
+    end
+
+    # Writes the audit line for one audited call, timed from `started`.
+    # :nodoc:
+    def record_call!(request, tool, started, **fields)
+      record!(request.bluebook_name, tool: tool, duration_ms: elapsed_ms(started), **audit_fields(request), **fields)
     end
 
     # :nodoc:
-    def audit_fields(request) = request.to_h.slice(:summary, :source, :role, :actor_id)
+    def audit_fields(request) = request.to_h.slice(:summary, :source, :role, :actor_id, :surface)
 
     # dry_run? (Runtime::Dispatcher) only understands the pre-envelope flat
     # args shape; this is the one entry point back into it from dispatch's own envelope.

data/lib/hecks/tickets/bluebook/adapters/work_areas.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/work_areas"
+
+Hecks.adapter "WorkAreas" do
+  port "WorkAreas"
+end

data/lib/hecks/tickets/bluebook/adapters/work_limits.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/work_limits"
+
+Hecks.adapter "WorkLimits" do
+  port "WorkLimits"
+end

data/lib/hecks/tickets/bluebook/tickets.behaviors

@@ -0,0 +1,70 @@
+Hecks.behaviors "Tickets" do
+  vision "A step of a plan moves planned, started, done; or it is dropped with a reason, or lapses with its decision."
+
+  loads "tickets.bluebook", "tickets.hecksagon", "tickets.ports.hecksagon"
+
+  test "Plan enters a step as planned" do
+    tests "Plan", on: "Work"
+    input work: { value: "w1" }, title: { value: "Add the everyday list" }, step: { value: 1 }
+    expect status: "planned"
+  end
+
+  test "Plan refuses a step with no title" do
+    tests "Plan", on: "Work"
+    input work: { value: "w2" }, title: { value: "" }
+    expect refused: "a piece of work has a title"
+  end
+
+  test "Plan refuses a negative step" do
+    tests "Plan", on: "Work"
+    input work: { value: "w3" }, title: { value: "Too early" }, step: { value: -1 }
+    expect refused: "a step is not negative"
+  end
+
+  test "Start moves a planned step to started" do
+    tests "Start", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w4" }, title: { value: "Declare for:" }
+    input  work: { value: "w4" },
+           claimed_by: { value: "session-1" }, claimed_at: { value: "2026-11-01T00:00:00Z" }
+    expect status: "started"
+  end
+
+  test "Finish closes a started step as done" do
+    tests "Finish", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w5" }, title: { value: "Declare the run kind" }
+    setup  "Tickets::Work.Start", work: { value: "w5" },
+           claimed_by: { value: "session-1" }, claimed_at: { value: "2026-11-01T00:00:00Z" }
+    input  work: { value: "w5" }
+    expect status: "done"
+  end
+
+  test "Finish closes a planned step that was never started" do
+    tests "Finish", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w6" }, title: { value: "A one-line change" }
+    input  work: { value: "w6" }
+    expect status: "done"
+  end
+
+  test "Drop sets a step aside with the reason" do
+    tests "Drop", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w7" }, title: { value: "The context candidates query" }
+    input  work: { value: "w7" }, reason: { value: "modules inside one context need no boundary finder" }
+    expect status: "dropped"
+  end
+
+  test "Lapse drops a step whose decision was superseded" do
+    tests "Lapse", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w8" }, title: { value: "A step of a replaced plan" }
+    input  work: { value: "w8" }
+    expect status: "dropped"
+  end
+
+  test "Start refuses a step that is already done" do
+    tests "Start", on: "Work"
+    setup  "Tickets::Work.Plan", work: { value: "w9" }, title: { value: "Finished early" }
+    setup  "Tickets::Work.Finish", work: { value: "w9" }
+    input  work: { value: "w9" },
+           claimed_by: { value: "session-1" }, claimed_at: { value: "2026-11-01T00:00:00Z" }
+    expect refused: "done"
+  end
+end