ace-herdr 0.1.0

data/lib/ace/herdr/cli/commands/deliver.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Deliver < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Push an answer to an agent pane (ace-hitl delivery contract)
+
+            Delivers are idempotent per event id and never lose the answer:
+            a write-ahead record survives crashes, missing agents are
+            bootstrapped, and transient failures retry with fixed backoff.
+          DESC
+
+          example [
+            "--session ws-1 --pane p5 --event-id evt-1 --answer-file answer.md",
+            "echo 'the answer' | ace-herdr deliver --pane p5",
+            "--session ws-1 --pane p5 --kind codex --label 8wm.t.vs0 (bootstraps if missing)"
+          ]
+
+          option :session, type: :string, desc: "Ref session (default: HERDR_SESSION)"
+          option :pane, type: :string, desc: "Ref pane (default: HERDR_PANE)"
+          option :event_id, type: :string, desc: "Idempotency key (derived from ref and content when omitted)"
+          option :kind, type: :string, desc: "Agent kind used when bootstrapping (default: config default_agent_kind)"
+          option :label, type: :string, desc: "Agent name used when bootstrapping (default: event id)"
+          option :answer_file, type: :string, desc: "Answer file (default: stdin)"
+          option :resume, type: :string, desc: "Event id to re-deliver from the stored record (crash recovery)"
+
+          def initialize(executor: nil)
+            @executor = executor
+          end
+
+          def call(**options)
+            translate_errors do
+              deliverer = Organisms::Deliverer.from_config(
+                executor: executor, deliveries_dir: deliveries_dir, config: config
+              )
+              if options[:resume]
+                result = deliverer.resume(options[:resume], kind: options[:kind], label: options[:label])
+                puts JSON.generate(ref: result.ref.to_h, state: result.state.to_s, resumed: true)
+                cli_error("delivery did not complete (state: #{result.state})") unless result.state == :delivered
+                return
+              end
+
+              ref = resolve_ref(options[:session], options[:pane])
+              answer = read_content(options[:answer_file], what: "answer")
+              result = deliverer.deliver(
+                ref, answer,
+                event_id: options[:event_id], kind: options[:kind], label: options[:label]
+              )
+              puts JSON.generate(ref: result.ref.to_h, state: result.state.to_s)
+              cli_error("delivery did not complete (state: #{result.state})") unless result.state == :delivered
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/dispatch.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Dispatch < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Start an agent in one command: tab + agent start + prompt
+
+            Defaults are deterministic: the caller's workspace, the label as
+            agent and pane name, the prompt from a file or stdin. Zero-token.
+          DESC
+
+          example [
+            "--label 8wm.t.vs0 --kind pi --prompt-file prompt.md",
+            "--label review --pane p7 --cwd /Users/me/project",
+            "--label 8wm.t.vs0 --no-prompt"
+          ]
+
+          option :label, type: :string, desc: "Agent and pane label (typically the task id)"
+          option :kind, type: :string, desc: "Agent kind (default: config default_agent_kind)"
+          option :workspace, type: :string, desc: "Target workspace (default: caller's workspace)"
+          option :pane, type: :string, desc: "Existing pane (default: create a new tab)"
+          option :cwd, type: :string, desc: "Working directory for a created tab"
+          option :prompt_file, type: :string, desc: "Prompt file (default: stdin)"
+          option :no_prompt, type: :boolean, desc: "Start the agent without submitting a prompt"
+
+          def initialize(executor: nil)
+            @executor = executor
+          end
+
+          def call(**options)
+            translate_errors do
+              cli_error("--label is required") if options[:label].to_s.empty?
+              prompt =
+                if options[:no_prompt]
+                  ""
+                else
+                  read_content(options[:prompt_file], what: "prompt")
+                end
+              dispatcher = Organisms::Dispatcher.from_config(executor: executor, config: config)
+              outcome = dispatcher.dispatch(
+                label: options.fetch(:label), prompt: prompt,
+                kind: options[:kind], workspace_id: options[:workspace],
+                pane: options[:pane], cwd: options[:cwd]
+              )
+              puts JSON.generate(outcome.to_h)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/list.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class List < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            List live herdr panes, tabs, or workspaces as one JSON line
+
+            Panes are the default scope; --workspace scopes panes and tabs.
+          DESC
+
+          example [
+            "                         # Panes across all workspaces",
+            "--workspace w1           # Panes in one workspace",
+            "--tabs --workspace w1    # Tabs in one workspace",
+            "--workspaces             # Workspaces"
+          ]
+
+          option :panes, type: :boolean, desc: "List panes (default)"
+          option :tabs, type: :boolean, desc: "List tabs"
+          option :workspaces, type: :boolean, desc: "List workspaces"
+          option :workspace, type: :string, desc: "Scope panes/tabs to a workspace id"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(executor: nil)
+            @executor = executor
+          end
+
+          def call(**options)
+            translate_errors do
+              scope = selected_scope(options)
+              cli_error("Use only one of --panes, --tabs, or --workspaces") if scope == :ambiguous
+              cli_error("--workspaces does not accept --workspace") if scope == :workspaces && options[:workspace]
+
+              control = Organisms::ControlSurface.new(executor: executor)
+              payload =
+                case scope
+                when :workspaces
+                  {workspaces: control.list_workspaces}
+                when :tabs
+                  {tabs: control.list_tabs(workspace_id: options[:workspace])}
+                else
+                  {panes: control.list_panes(workspace_id: options[:workspace])}
+                end
+              puts JSON.generate(payload) unless options[:quiet]
+            end
+          end
+
+          private
+
+          def selected_scope(options)
+            scopes = %i[panes tabs workspaces].select { |key| options[key] }
+            return :ambiguous if scopes.length > 1
+
+            scopes.first || :panes
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/list_presets.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class ListPresets < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            List available workspace/tab presets as one JSON line
+
+            The inventory reflects the merged ADR-022 cascade: gem defaults
+            under .ace-defaults/herdr/, overridden by ~/.ace/herdr/ and the
+            project .ace/herdr/.
+          DESC
+
+          example [
+            "",
+            "workspaces",
+            "tabs"
+          ]
+
+          argument :type, required: false, desc: "Scope: workspaces or tabs (default: both)"
+
+          def initialize(executor: nil, control: nil)
+            @executor = executor
+            @control = control
+          end
+
+          def call(type: nil, **options)
+            translate_errors do
+              control = @control || Organisms::ControlSurface.new(executor: executor)
+              puts JSON.generate(control.list_presets(type: type))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/send.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Send < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Send a command, raw text, or named keys to a pane
+
+            Input reaches the pane in declaration order. Panes hosting a
+            live agent get prompt semantics: text becomes one self-submitting
+            agent prompt (agent_blocked is rejected pre-send) and a single
+            trailing --key Enter is dropped and reported.
+          DESC
+
+          example [
+            "--pane p5 --cmd 'bundle exec rake test'",
+            "--pane p5 --msg 'continue with option 2' --key Enter",
+            "--pane p5 --key Esc --cmd 'reset'",
+            "--pane p5 --key Enter",
+            "--pane p5 --cmd 'y' --quiet"
+          ]
+
+          option :pane, type: :string, desc: "Target pane id"
+          option :cmd, type: :string, aliases: %w[-c], desc: "Command text to submit (at most one, before any --key)"
+          option :msg, type: :string, aliases: %w[-m], repeat: true, desc: "Literal text to type without submitting"
+          option :key, type: :string, aliases: %w[-k], repeat: true, desc: "Named key to send (for example enter, esc, ctrl+c)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(executor: nil, argv_source: nil)
+            @executor = executor
+            @argv_source = argv_source
+          end
+
+          def call(**options)
+            translate_errors do
+              cli_error("--pane is required") if options[:pane].to_s.empty?
+              control = Organisms::ControlSurface.new(executor: executor)
+              result = control.send_input(pane: options.fetch(:pane), tokens: input_tokens(options))
+              puts JSON.generate(result) unless options[:quiet]
+            end
+          end
+
+          private
+
+          # Declaration order carries meaning (spec 8wq.t.k84), so the argv
+          # token stream is the source of truth for real invocations. Parsed
+          # option arrays only back programmatic calls with no input flags on
+          # the command line (canonical order: cmd, msgs, keys).
+          def input_tokens(options)
+            argv_tokens(@argv_source || ARGV) || option_tokens(options)
+          end
+
+          def argv_tokens(argv)
+            tokens = []
+            seen_input_flag = false
+            index = 0
+            while index < argv.length
+              token = argv[index]
+              if (match = token.match(/\A(--cmd|-c|--msg|-m|--key|-k)=(.*)\z/m))
+                seen_input_flag = true
+                tokens << {type: flag_type(match[1]), value: match[2]}
+                index += 1
+              elsif (flag = %w[--cmd -c --msg -m --key -k].include?(token) && token)
+                seen_input_flag = true
+                tokens << {type: flag_type(flag), value: argv[index + 1]}
+                index += 2
+              else
+                index += 1
+              end
+            end
+            seen_input_flag ? tokens : nil
+          end
+
+          def flag_type(flag)
+            case flag
+            when "--cmd", "-c" then :cmd
+            when "--msg", "-m" then :msg
+            else :key
+            end
+          end
+
+          def option_tokens(options)
+            tokens = []
+            tokens << {type: :cmd, value: options[:cmd]} if options[:cmd]
+            Array(options[:msg]).each { |value| tokens << {type: :msg, value: value} }
+            Array(options[:key]).each { |value| tokens << {type: :key, value: value} }
+            tokens
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/support.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        # Shared collaborator construction for ace-herdr commands. The
+        # executor is injectable so tests can substitute a fake; commands
+        # registered in the CLI use the real herdr binary.
+        module Runtime
+          def executor
+            @executor ||= Ace::Herdr::Molecules::HerdrExecutor.new
+          end
+
+          def config
+            @config ||= Ace::Herdr.config
+          end
+
+          def deliveries_dir
+            File.expand_path(config["deliveries_dir"] || ".ace-local/herdr/deliveries", Dir.pwd)
+          end
+
+          # Reverse address from flags or the caller's herdr environment,
+          # fail closed (spec 8wm.t.vrz §3)
+          def resolve_ref(session, pane)
+            Ace::Hitl::Providers::Ref.new(
+              session: Ace::Hitl::Providers::Ref.validate!(
+                session || ENV["HERDR_SESSION"], "HERDR_SESSION"
+              ),
+              pane: Ace::Hitl::Providers::Ref.validate!(
+                pane || ENV["HERDR_PANE"], "HERDR_PANE"
+              )
+            )
+          end
+
+          # Answer/prompt content from a file or stdin
+          def read_content(path, what:)
+            return $stdin.read if path.nil? || path.empty?
+
+            File.read(path)
+          rescue Errno::ENOENT
+            raise Ace::Support::Cli::Error, "#{what} file not found: #{path}"
+          end
+
+          def cli_error(message)
+            raise Ace::Support::Cli::Error, message
+          end
+
+          # Contract and executor failures become CLI errors (ADR-023)
+          def translate_errors
+            yield
+          rescue Ace::Hitl::Providers::InvalidRefError,
+            Ace::Hitl::Providers::ProviderUnavailableError,
+            Ace::Herdr::ValidationError,
+            Ace::Herdr::TargetResolutionError,
+            Ace::Herdr::WaitTimeoutError,
+            Ace::Herdr::ExecutorError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/tab.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Tab < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Create a tab from a preset (≈ ace-tmux window)
+
+            The tab lands in the caller's workspace unless --workspace is
+            given. Presets resolve through the ADR-022 cascade and may
+            compose via `preset:` refs; --cwd overrides the resolved tab cwd.
+          DESC
+
+          example [
+            "agent",
+            "agent --workspace w1",
+            "agent --cwd /path/to/project"
+          ]
+
+          argument :preset, desc: "Tab preset name (list with ace-herdr --list-presets tabs)"
+          option :workspace, type: :string, desc: "Target workspace (default: caller's workspace)"
+          option :cwd, type: :string, desc: "Working directory overriding the resolved tab/pane cwd"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(executor: nil, control: nil)
+            @executor = executor
+            @control = control
+          end
+
+          def call(preset: nil, **options)
+            translate_errors do
+              cli_error("preset name is required") if preset.to_s.empty?
+              control = @control || Organisms::ControlSurface.from_config(executor: executor, config: config)
+              result = control.create_tab(
+                preset, workspace_id: options[:workspace], cwd: options[:cwd]
+              )
+              puts JSON.generate(result) unless options[:quiet]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/tidy.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Tidy < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Report cleanable agent panes and delivery records as one JSON line
+
+            Dry run by default: nothing is closed or removed. With --apply,
+            panes close only on positive completion evidence (observed done
+            state or dead pane process) re-confirmed right before closing;
+            delivered records older than tidy.delivered_retention_days are
+            archived. Unknown, unreadable, pending, retryable, and failed
+            resources are never touched.
+          DESC
+
+          example [
+            "         # Dry run: report candidates only",
+            "--apply  # Close eligible panes, archive old delivered records",
+            "--quiet  # Suppress the report"
+          ]
+
+          option :apply, type: :boolean, desc: "Close eligible panes and archive old delivered records (default: dry run)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(executor: nil, config: nil)
+            @executor = executor
+            @injected_config = config
+          end
+
+          def call(**options)
+            translate_errors do
+              report = tidy.run(apply: options[:apply] || false)
+              puts JSON.generate(report) unless options[:quiet]
+            end
+          end
+
+          private
+
+          def config
+            @injected_config || super
+          end
+
+          def tidy
+            Organisms::Tidy.new(
+              executor: executor,
+              deliveries_dir: deliveries_dir,
+              retention_days: (config["tidy"] || {})["delivered_retention_days"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/wait.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Wait < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Wait for an agent state or matching pane output
+
+            --for agent (default) waits for an agent state without scraping
+            pane output. --for output waits until the pane content contains
+            the literal --pattern; existing content is checked immediately,
+            then polled.
+          DESC
+
+          example [
+            "--pane p5",
+            "--pane p5 --until done --timeout 120",
+            "--pane p5 --for output --pattern 'build succeeded'",
+            "--pane p5 --for output --pattern done --timeout 30"
+          ]
+
+          option :pane, type: :string, desc: "Target pane id"
+          option :for, type: :string, desc: "What to wait for: agent (default) or output"
+          option :until, type: :string, desc: "Agent states, comma-separated: idle,working,blocked,done,unknown (default: idle,done,blocked)"
+          option :pattern, type: :string, desc: "Literal output pattern to wait for (with --for output)"
+          option :timeout, type: :integer, desc: "Timeout in seconds (default: config timeouts.wait)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(executor: nil)
+            @executor = executor
+          end
+
+          def call(**options)
+            translate_errors do
+              cli_error("--pane is required") if options[:pane].to_s.empty?
+              mode = options[:for] || "agent"
+              unless %w[agent output].include?(mode)
+                cli_error("--for must be agent or output")
+              end
+              timeout_seconds =
+                options[:timeout] || (config.dig("timeouts", "wait") || 30)
+
+              if mode == "output"
+                wait_for_output(options, timeout_seconds)
+              else
+                wait_for_agent(options, timeout_seconds)
+              end
+            end
+          end
+
+          private
+
+          def wait_for_agent(options, timeout_seconds)
+            cli_error("--pattern requires --for output") if options[:pattern]
+            until_states = (options[:until] || "idle,done,blocked")
+              .split(",").map(&:strip).reject(&:empty?)
+            executor.agent_wait(
+              pane: options.fetch(:pane), until_states: until_states,
+              timeout_ms: timeout_seconds * 1000
+            )
+            puts JSON.generate(pane: options.fetch(:pane), state: "ready") unless options[:quiet]
+          end
+
+          def wait_for_output(options, timeout_seconds)
+            cli_error("--for output requires --pattern") if options[:pattern].to_s.empty?
+            cli_error("--until requires --for agent") if options[:until]
+            control = Organisms::ControlSurface.new(executor: executor)
+            control.wait_output(
+              pane: options.fetch(:pane), pattern: options.fetch(:pattern),
+              timeout_ms: timeout_seconds * 1000
+            )
+            puts JSON.generate(pane: options.fetch(:pane), matched: true) unless options[:quiet]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/cli/commands/workspace.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Herdr
+    module CLI
+      module Commands
+        class Workspace < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Create a workspace from a preset (≈ ace-tmux start)
+
+            Presets resolve through the ADR-022 cascade (.ace/herdr/ >
+            ~/.ace/herdr/ > gem defaults) and may compose via `preset:` refs.
+            Tabs, panes, splits, commands, and agents are created in declared
+            order; --cwd overrides the resolved root/tab cwd.
+          DESC
+
+          example [
+            "development",
+            "development --cwd /path/to/project",
+            "development --quiet"
+          ]
+
+          argument :preset, desc: "Workspace preset name (list with ace-herdr --list-presets workspaces)"
+          option :cwd, type: :string, desc: "Working directory overriding the resolved root/tab cwd"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(executor: nil, control: nil)
+            @executor = executor
+            @control = control
+          end
+
+          def call(preset: nil, **options)
+            translate_errors do
+              cli_error("preset name is required") if preset.to_s.empty?
+              control = @control || Organisms::ControlSurface.from_config(executor: executor, config: config)
+              result = control.create_workspace(preset, cwd: options[:cwd])
+              puts JSON.generate(result) unless options[:quiet]
+            end
+          end
+        end
+      end
+    end
+  end
+end