robot_lab 0.2.1 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '020282572c5c4eca7e0c44d60920752df53043df99aa54a2018b68e049404945'
-  data.tar.gz: 2f0d0e92ff91a8eb24ff73065e1b91091c57cb6abcf3a0c3349c2370ab877973
+  metadata.gz: 36b770d963e004a951cdf35d07a2e867e4e661a9e342e8047184cfd9dafd6e15
+  data.tar.gz: f53bb5c52efcd6169bf36afc69306a9c03e9cfcabdaf5b0a94871802e2909f55
 SHA512:
-  metadata.gz: 7d99549cbb526071e48e2d66e9771553491404ec437f21465190517fc4451418a48024cd5e1fc8482ae96ea061492fb632f8f264048d8941e20090faa1213d22
-  data.tar.gz: 0fe87b21e72c03a65e3809dfab01d3d6735919101ab8f2f8d9cd9d64a52394c06fc12f9fc9b648cb9350568c56ac8da111d8a6db9ba841738cbb72ce682708d6
+  metadata.gz: 850bde0e9ac1b7d65176bd067f42751d6d9db64517ca665d4765837fc5493e204f9b333cac08019cb451962d4d95789f986dee2ff08e55ae5e6a0d3d034f4f50
+  data.tar.gz: 97eb4dc66458a9a43f861e3f9c927eb6cfa63d33ddfff150b4181a45dc2c0db9570095f2e71d1182b76b4ee85e7086a6014b5536e805d9956f0860f9b4a03f50

data/.envrc

@@ -1 +1,2 @@
 export RR=`pwd`
+export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# robot_lab core — development tasks.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab".freeze
+
+  header "robot_lab v#{gem_version} — core multi-robot LLM framework"
+
+  desc "Run integration tests only"
+  def integration
+    sh "bundle exec rake integration"
+  end
+
+  desc "Run a single test file (e.g. asgard test_file test/robot_test.rb)"
+  def test_file(path)
+    sh "ruby -Ilib:test \"#{path}\""
+  end
+
+  class DocsCommands < Tasks
+    desc "Build YARD + MkDocs documentation"
+    def build
+      sh "bundle exec rake docs:build"
+    end
+
+    desc "Serve MkDocs documentation at http://localhost:8000"
+    def serve
+      sh "mkdocs serve"
+    end
+
+    desc "Serve YARD documentation locally"
+    def yard
+      sh "yard server --reload"
+    end
+  end
+
+  class ExamplesCommands < Tasks
+    desc "Run all examples (skips standalone apps and external-service examples)"
+    def all
+      sh "bundle exec rake examples:all"
+    end
+
+    desc "exec N", "Run a specific example by number (e.g. asgard examples exec 3)"
+    def exec(num)
+      sh "bundle exec rake examples:run[#{num}]"
+    end
+
+    desc "Start the Rails demo app (example 18)"
+    def rails
+      sh "bundle exec rake examples:rails"
+    end
+  end
+
+  desc "docs SUBCOMMAND", "Documentation tasks (build, serve, yard)"
+  subcommand "docs", DocsCommands
+
+  desc "examples SUBCOMMAND", "Example tasks (all, exec N, rails)"
+  subcommand "examples", ExamplesCommands
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1,43 @@
+4	lib/robot_lab.rb
+1	lib/robot_lab/agent_skill_catalog.rb
+2	lib/robot_lab/ask_user.rb
+2	lib/robot_lab/bus_poller.rb
+4	lib/robot_lab/capabilities.rb
+8	lib/robot_lab/config.rb
+3	lib/robot_lab/doom_loop_detector.rb
+6	lib/robot_lab/history_compressor.rb
+1	lib/robot_lab/hook.rb
+4	lib/robot_lab/hook_context.rb
+1	lib/robot_lab/hook_registry.rb
+4	lib/robot_lab/hooks.rb
+3	lib/robot_lab/mcp/client.rb
+6	lib/robot_lab/mcp/connection_poller.rb
+1	lib/robot_lab/mcp/server_discovery.rb
+3	lib/robot_lab/mcp/transports/sse.rb
+6	lib/robot_lab/mcp/transports/stdio.rb
+4	lib/robot_lab/mcp/transports/streamable_http.rb
+3	lib/robot_lab/mcp/transports/websocket.rb
+16	lib/robot_lab/memory.rb
+1	lib/robot_lab/memory_change.rb
+3	lib/robot_lab/message.rb
+8	lib/robot_lab/network.rb
+70	lib/robot_lab/robot.rb
+2	lib/robot_lab/robot/agent_skill_matching.rb
+4	lib/robot_lab/robot/bus_messaging.rb
+2	lib/robot_lab/robot/history_search.rb
+2	lib/robot_lab/robot/hooking.rb
+9	lib/robot_lab/robot/mcp_management.rb
+8	lib/robot_lab/robot/template_rendering.rb
+4	lib/robot_lab/robot_result.rb
+5	lib/robot_lab/run_config.rb
+1	lib/robot_lab/sandbox.rb
+1	lib/robot_lab/sandbox/seatbelt.rb
+3	lib/robot_lab/script_tool.rb
+1	lib/robot_lab/state_proxy.rb
+1	lib/robot_lab/streaming/context.rb
+1	lib/robot_lab/streaming/events.rb
+2	lib/robot_lab/task.rb
+6	lib/robot_lab/tool.rb
+2	lib/robot_lab/user_message.rb
+2	lib/robot_lab/utils.rb
+2	lib/robot_lab/waiter.rb

data/.rubocop.yml

@@ -1,172 +1,10 @@
+inherit_from: ../.rubocop-base.yml
+
+# Core-only overrides. Exclude patterns here are relative to this repo and
+# merge with the shared base's excludes.
 AllCops:
-  NewCops: enable
-  SuggestExtensions: false
-  TargetRubyVersion: 4.0
   Exclude:
-    - 'examples/**/*'
-    - 'vendor/**/*'
-    - 'dead_code/**/*'
     - '_notes/**/*'
 
-# ── Style: disabled cops ───────────────────────────────────────────────────
-Style/StringLiterals:
-  Enabled: false
-
-Style/StringLiteralsInInterpolation:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-# Ruby 4.0 freezes string literals by default
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-Style/IfUnlessModifier:
-  Enabled: false
-
-Style/RescueModifier:
-  Enabled: false
-
-Style/TrivialAccessors:
-  Enabled: false
-
-Style/MultilineTernaryOperator:
-  Enabled: false
-
-Style/SafeNavigation:
-  Enabled: false
-
-Style/EmptyClassDefinition:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-Style/RescueStandardError:
-  Enabled: false
-
-Style/OneClassPerFile:
-  Enabled: false
-
-# Both % and format/sprintf are acceptable
-Style/FormatString:
-  Enabled: false
-
-# String concatenation and interpolation are both acceptable
-Style/StringConcatenation:
-  Enabled: false
-
-# ── Layout ─────────────────────────────────────────────────────────────────
-Layout/LineLength:
-  Max: 140
-
-Layout/ExtraSpacing:
-  Enabled: false
-
-Layout/HashAlignment:
-  Enabled: false
-
-Layout/FirstHashElementIndentation:
-  Enabled: false
-
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-
-# ── Naming ─────────────────────────────────────────────────────────────────
-# Single-char params (c, e, n) are acceptable throughout
-Naming/MethodParameterName:
-  Enabled: false
-
-Naming/VariableNumber:
-  Exclude:
-    - 'test/**/*'
-
-Naming/RescuedExceptionsVariableName:
-  Enabled: false
-
-# set_results and similar explicit setters are clear and conventional
-Naming/AccessorMethodName:
-  Enabled: false
-
-# has_tool_calls? and similar are clear and conventional
-Naming/PredicatePrefix:
-  Enabled: false
-
-# Test helper methods don't need to follow predicate naming rules
-Naming/PredicateMethod:
-  Exclude:
-    - 'test/**/*'
-
-# ── Lint: relax noisy cops on intentional patterns ─────────────────────────
-Lint/EmptyBlock:
-  Exclude:
-    - 'test/**/*'
-
-# Library and framework methods commonly accept args for API/documentation purposes
-Lint/UnusedMethodArgument:
-  Enabled: false
-
-Lint/ConstantDefinitionInBlock:
-  Exclude:
-    - 'Rakefile'
-    - 'test/**/*'
-
-# ── Gemspec ────────────────────────────────────────────────────────────────
-Gemspec/DevelopmentDependencies:
-  EnforcedStyle: Gemfile
-
-Gemspec/RequiredRubyVersion:
-  Enabled: false
-
-Gemspec/OrderedDependencies:
-  Enabled: false
-
-# ── Metrics ────────────────────────────────────────────────────────────────
-# Framework-level code (routers, parsers, orchestrators) is inherently complex.
-# Flog is the primary complexity gate — these RuboCop thresholds catch only
-# egregious outliers without false-positiving every dispatch method.
-
-Metrics/MethodLength:
-  Max: 35
-  CountAsOne:
-    - heredoc
-    - array
-    - hash
-  Exclude:
-    - 'test/**/*'
-
-Metrics/AbcSize:
-  Max: 40
-  Exclude:
-    - 'test/**/*'
-
 Metrics/ClassLength:
-  Max: 600
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ModuleLength:
-  Max: 200
-  Exclude:
-    - 'test/**/*'
-
-Metrics/CyclomaticComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-Metrics/PerceivedComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-# Long method signatures with keyword args are a Ruby framework idiom
-Metrics/ParameterLists:
-  Enabled: false
-
-Metrics/BlockLength:
-  Exclude:
-    - 'Rakefile'
-    - '*.gemspec'
-    - 'test/**/*'
+  Max: 650 # Robot is the central class; a future refactor could split it further

data/CHANGELOG.md

@@ -8,6 +8,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `BusMessaging#respond_to_tasks` and `#serve` — a member auto-answers inbound
+  (non-reply) bus tasks and replies to the sender. `serve` runs each task through
+  `#run`; `respond_to_tasks { |m| ... }` is the generic form. Makes a Robot a
+  first-class bus responder (symmetric with how a Cyborg answers its human)
+  without hand-wiring `on_message`.
+- `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, `integration`, `docs`, and `examples` tasks via the Asgard task runner
+
+### Fixed
+- `BusMessaging` now synchronizes its message counter and outbox with a mutex, so
+  concurrent sends and poller-thread reply correlation can't clobber each other.
+- `flay_check` Rake task: structural code duplication gate (mass threshold 50); integrated into the `quality` Rake task
+- `flay` gem added to development dependencies
+- `test_output.txt`, `flay_output.txt`, `flog_output.txt`, and `rubocop_output.txt` added to `.gitignore`
+
+### Changed
+- `test/test_helper.rb`: test output redirected to `test_output.txt` via `$stdout` reassignment; `TerminalSummaryReporter` prints a single PASS/FAIL summary line to the terminal
+- `Rakefile`: `rubocop` and `rubocop_fix` tasks removed (now owned by Asgard); `flay_check` integrated into the `quality` gate
+
+## [0.2.6] - 2026-05-23
+
+### Added
+
+- **`:compaction` hook family** — fires when `maybe_compact` determines that conversation history should be compressed. Provides `before_compaction`, `around_compaction`, `after_compaction`, and `on_compaction` callbacks.
+  - `on_compaction` allows an extension to supply a complete replacement message set via `ctx.compacted_messages`; when set, the core skips its own compaction strategy entirely (`ctx.handled?` returns true).
+  - `CompactionHookContext` — carries `robot`, `messages_before` (frozen snapshot), `config`, `strategy` (`:context_window`, `:custom`, or other symbol), `compacted_messages`, and `handled?`.
+- **`:learn` hook family** — fires on every `robot.learn(text)` call with non-empty text. Provides `before_learn`, `around_learn`, `after_learn`, and `on_learn` callbacks.
+  - `on_learn` fires after the text has been stored and `ctx.stored = true`, giving extensions a reliable hook point for cross-session persistence.
+  - `LearnHookContext` — carries `robot`, `text`, `learnings_before` (frozen snapshot), and `stored`.
+- **`over_compact_threshold?`** private predicate extracted from `compact_if_over_context_window` for independent testability.
+- Hook tests for both new families added to `test/robot_lab/hooks_test.rb` (18 new tests across `RobotLabCompactionHooksTest` and `RobotLabLearnHooksTest`).
+- Documentation for `:compaction` and `:learn` hook families added to `docs/guides/hooks.md`.
+
+### Changed
+
+- **`Robot#on`** now accepts and forwards `context:` to `HookRegistry#on`, allowing extensions to pass per-registration domain config at registration time (e.g. `robot.on(MyHook, context: { domain: "finance" })`). Previously `context:` was silently dropped.
+- **`maybe_compact`** refactored to dispatch through the `:compaction` hook family and delegate to `on_compaction` before falling back to the built-in strategy.
+- **`Robot#learn`** refactored to dispatch through the `:learn` hook family; `on_learn` fires after deduplication with `ctx.stored` reflecting whether the text was actually added.
+
+### Added
+
+- **`RobotLab::Hook` base class** (`lib/robot_lab/hook.rb`) — all hook handlers inherit from this class. Subclasses define lifecycle callbacks as `class << self` methods (`before_run`, `after_run`, etc.). Namespace is auto-derived from the class name via snake_case conversion of the final class name segment (e.g. `AuditHook` → `:audit_hook`); override with `self.namespace = :custom`. Ractor-safe by design: handler classes are Ruby constants, not Procs, so registrations are natively serializable across Ractor boundaries.
+- **Hook system** — lifecycle hooks across all execution boundaries. Register handler classes with `RobotLab.on`, `network.on`, or `robot.on` for five families: `:run`, `:llm_generation`, `:tool_call`, `:network_run`, and `:task`, each with `before_*`, `around_*`, `after_*`, and (where applicable) `on_error` variants.
+  - `HookRegistry::Registration` — `Data.define(:handler_class, :context)`; stores a handler class reference and optional per-registration default `DotState` values. No Proc, no namespace field — namespace is read from the handler class.
+  - `HookContext` and five typed subclasses: `RunHookContext`, `LlmGenerationHookContext`, `ToolCallHookContext`, `NetworkRunHookContext`, `TaskHookContext` — unchanged
+  - `DotState` / `ExtensionState` — namespace-isolated dot-access state carried on every context object; `ctx.local` reads/writes state for the active handler's namespace
+  - `context:` parameter on `on(handler_class, context: {...})` — sets per-registration default `DotState` values merged in before each callback fires
+  - Around hooks chain correctly across handler class registrations; return value is propagated up the chain
+  - Per-run hooks via `robot.run("msg", hooks: MyHook)` or `robot.run("msg", hooks: [MyHook, OtherHook])`
+  - `on_error` fires for `:run`, `:network_run`, and `:task` families; exception is re-raised after all error handlers complete
+- **`examples/xyzzy.rb`** — updated reference extension: `RobotLab::Xyzzy < RobotLab::Hook` with `class << self` methods for every hook family; logs each callback with a timestamped stdout tagline and a structured logger context snapshot; registered globally with `RobotLab.on(RobotLab::Xyzzy)`
+- **Example 35** (`examples/35_hooks.rb`) — updated full hook pipeline demo: xyzzy extension tracing all hooks, `around_run` perf timer handler class, `around_llm_generation` response cache handler class (cache hits skip the LLM entirely), `before/after_llm_generation` tracer, tool call hooks, network/task hooks, and `on_error`
+- **`examples/common.rb`** — added explicit `openai_api_key`, `openai_organization_id`, and `openai_project_id` to `RubyLLM.configure` to match provider configurator expectations; updated default model to `gpt-4.1-mini`
+
 ## [0.2.1] - 2026-05-19
 
 ### Added