robot_lab 0.2.6 → 0.2.8

data/docs/api/skills.md

@@ -0,0 +1,423 @@
+# Skills API
+
+Class-level reference for the AgentSkills subsystem: skill bundles, the scripts
+they expose as tools, and the capabilities those scripts declare. Core itself
+has **no sandboxing and no execution limitations** — every script runs
+unconfined until the optional
+[`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox) gem is
+required, at which point it installs a confinement strategy (see
+[ScriptTool.executor](#scripttoolexecutor) below). For the how-to, see
+[Using Tools: Skill Scripts and Sandboxing](../guides/using-tools.md#skill-scripts-and-sandboxing)
+and [Building Robots: Composable Skills](../guides/building-robots.md#composable-skills).
+
+!!! note "Two different things are called 'skills'"
+    **Template skills** (`RobotLab.build(skills: [:clarifier])`) are ordinary
+    prompt templates whose bodies are prepended to a robot's system prompt — see
+    [Robot: Skills](core/robot.md#skills). **AgentSkills** (this page) are
+    `SKILL.md` *bundles* on disk, discovered from `~/.prompts/skills/`, matched
+    to a message by embedding similarity at run time, and capable of contributing
+    executable tools. They share the word but not the mechanism.
+
+```mermaid
+graph LR
+    subgraph "Discovery"
+        C[AgentSkillCatalog<br/>~/.prompts/skills/]
+        S[AgentSkill<br/>SKILL.md]
+    end
+
+    subgraph "Capability grant"
+        D[Capabilities<br/>declared in front matter]
+        CE[Capabilities.ceiling<br/>from config.sandbox]
+        G[effective grant<br/>declared ∩ ceiling]
+    end
+
+    subgraph "Execution (core)"
+        T[ScriptTool.from_path<br/>-> RobotLab::Tool]
+        EX{ScriptTool.executor<br/>set?}
+        UN[Open3.capture2e<br/>unconfined, no timeout]
+    end
+
+    subgraph "robot_lab-sandbox (optional gem)"
+        SB{Sandbox.enabled?}
+        SE[Sandbox::Seatbelt<br/>macOS]
+        NU[Sandbox::Null<br/>passthrough]
+    end
+
+    R[Robot<br/>AgentSkillMatching] --> C
+    C --> S
+    S --> D
+    S --> T
+    D --> G
+    CE --> G
+    T --> EX
+    EX -- "nil (default)" --> UN
+    EX -- "installed" --> SB
+    SB -- "off, or trust: core,<br/>or non-macOS" --> NU
+    SB -- "on + macOS" --> SE
+    G --> SE
+```
+
+---
+
+## RobotLab::AgentSkill
+
+Immutable value object for one skill folder: a directory containing a `SKILL.md`
+with `name` and `description` front matter, plus optional `scripts/`,
+`references/`, and `assets/` subdirectories.
+
+### Constructor
+
+```ruby
+skill = RobotLab::AgentSkill.new("~/.prompts/skills/deploy-checker/SKILL.md")
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `skill_md_path` | `String`, `Pathname` | Path to the `SKILL.md` file itself, **not** the directory |
+
+**Raises `RobotLab::ConfigurationError`** when front matter is missing `name` or
+`description` (or either is blank) — and because a file with no `---` block
+parses to an empty hash, a `SKILL.md` without front matter always raises.
+Malformed YAML raises `Psych::SyntaxError` instead, straight from
+`YAML.safe_load`. [`AgentSkillCatalog`](#robotlabagentskillcatalog) rescues both
+and skips the bundle; construct an `AgentSkill` directly and you get the
+exception.
+
+### Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | `String` | Front-matter `name`; also the catalog lookup key (symbolized) |
+| `description` | `String` | Front-matter `description`; the text matched against the user's message |
+| `path` | `Pathname` | The skill **directory** (`dirname` of the `SKILL.md` path) |
+| `capabilities` | `Capabilities` | Built from front matter via `Capabilities.from_front_matter` |
+
+### instructions
+
+```ruby
+skill.instructions  # => String
+```
+
+The `SKILL.md` body below the front matter, stripped. This is the text
+`Robot::AgentSkillMatching` prepends to the system prompt when the skill matches.
+Memoized.
+
+### scripts
+
+```ruby
+skill.scripts  # => Array<Pathname>
+```
+
+Every **file** directly inside the skill's `scripts/` directory, sorted. Returns
+`[]` when there is no `scripts/` directory. Not recursive — subdirectories are
+skipped. Memoized.
+
+### script_tools
+
+```ruby
+skill.script_tools  # => Array<RobotLab::Tool>
+```
+
+One `RobotLab::Tool` per script, built with
+[`ScriptTool.from_path`](#scripttoolfrom_path) and carrying this skill's
+`capabilities` and directory. **Non-executable scripts are skipped** (logged at
+`warn` and filtered out by `filter_map`), so this array can be shorter than
+`scripts`. Memoized.
+
+These tools are appended to `robot.local_tools` for the duration of a matched
+`run` and removed again in the `ensure` block — see
+[Robot Execution](../architecture/robot-execution.md#execution-overview).
+
+---
+
+## RobotLab::AgentSkillCatalog
+
+Lazily-loaded registry of the skill folders under a root directory.
+
+### SKILLS_ROOT
+
+```ruby
+RobotLab::AgentSkillCatalog::SKILLS_ROOT
+# => #<Pathname:/Users/you/.prompts/skills>
+```
+
+`~/.prompts/skills`, expanded at load time. The path the process-level singleton
+scans.
+
+### instance / reset!
+
+```ruby
+RobotLab::AgentSkillCatalog.instance  # => the singleton, scanning SKILLS_ROOT
+RobotLab::AgentSkillCatalog.reset!    # => nil; next `instance` builds a fresh one
+```
+
+`instance` memoizes. `reset!` drops the memo — it exists so tests can point the
+catalog at a fixture directory by resetting and constructing an instance
+explicitly with a different root.
+
+### Constructor
+
+```ruby
+catalog = RobotLab::AgentSkillCatalog.new("/path/to/skills")
+```
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `skills_root` | `String`, `Pathname` | `SKILLS_ROOT` | Directory to scan |
+
+Construction does **no** I/O; the scan happens on the first `find`/`all`.
+
+### find
+
+```ruby
+catalog.find(:deploy_checker)   # => AgentSkill or nil
+catalog.find("deploy-checker")  # => AgentSkill or nil
+```
+
+Look up by skill **name** (the front-matter `name`, symbolized) — not by
+directory name, and not by file path. Returns `nil` when not found.
+
+### all
+
+```ruby
+catalog.all  # => Array<AgentSkill>
+```
+
+Every successfully-loaded skill.
+
+!!! note "Loading is lazy, thread-safe, and forgiving"
+    The scan runs once, under a `Mutex`, on the first `find` or `all`. A missing
+    root directory is not an error — the catalog is simply empty. A directory
+    without a `SKILL.md` is skipped silently; a `SKILL.md` that raises
+    `ConfigurationError` or `Psych::SyntaxError` is skipped with a `warn`
+    (`"AgentSkillCatalog: <message>, skipping <dir>"`). One bad bundle never
+    prevents the others from loading, and the scan is never retried.
+
+---
+
+## RobotLab::Capabilities
+
+What a skill's scripts may read, write, reach, and how long they may run.
+
+A skill declares what it **wants** in `SKILL.md` front matter; the global
+`sandbox:` config declares the **ceiling**. The effective grant is the
+[intersection](#intersect) of the two.
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `DEFAULT_TIMEOUT` | `60` | Seconds, used when `timeout` is absent or non-positive |
+| `TRUST_LEVELS` | `["core", "external"]` | Any other value falls back to `"external"` |
+
+### Constructor
+
+```ruby
+RobotLab::Capabilities.new(
+  fs_read: [], fs_write: [], network: false,
+  timeout: DEFAULT_TIMEOUT, trust: "external"
+)
+```
+
+| Name | Type | Default | Coercion |
+|------|------|---------|----------|
+| `fs_read` | `Array<String>` | `[]` | `Array(...)` then `to_s` on each entry |
+| `fs_write` | `Array<String>` | `[]` | Same |
+| `network` | `Boolean` | `false` | Any truthy value becomes `true` |
+| `timeout` | `Integer` | `60` | `to_i`; anything not positive becomes `DEFAULT_TIMEOUT` |
+| `trust` | `String` | `"external"` | Must be in `TRUST_LEVELS`, else `"external"` |
+
+Every value is normalized in the constructor, so the readers `fs_read`,
+`fs_write`, `network`, `timeout`, and `trust` always return well-formed values —
+a malformed `SKILL.md` degrades to the safe default rather than raising.
+
+### from_front_matter
+
+```ruby
+RobotLab::Capabilities.from_front_matter(front_matter_hash)  # => Capabilities
+```
+
+Build from a parsed `SKILL.md` front-matter hash, reading `fs_read`, `fs_write`,
+`network`, `timeout`, and `trust`. A `nil` front matter yields an all-defaults
+instance.
+
+### fm_value
+
+```ruby
+RobotLab::Capabilities.fm_value(front_matter, :network, false)
+```
+
+Look up a front-matter key tolerating **either** string or symbol keys (string
+first, then symbol), returning `default` when both are `nil`. Exposed because
+`from_front_matter` uses it and skill-tooling may need the same leniency.
+
+### ceiling
+
+```ruby
+RobotLab::Capabilities.ceiling                 # => from RobotLab.config.sandbox
+RobotLab::Capabilities.ceiling(custom_config)
+```
+
+The maximum grant any skill may receive, read from the config's `sandbox:`
+section. When there is no `sandbox` section at all, the ceiling is
+`Capabilities.new(fs_read: ["."])` — read-only access to the working directory,
+no writes, no network.
+
+Note the ceiling never carries a `trust` — trust is a property of the skill, not
+of the ceiling, and `intersect` keeps the declared value.
+
+### core?
+
+```ruby
+capabilities.core?  # => trust == "core"
+```
+
+A `core` skill is exempt from confinement: when `robot_lab-sandbox` is loaded,
+`Sandbox.for` returns a `Null` strategy for it regardless of platform or
+config. Reserve `trust: core` for bundles you wrote and audited.
+
+### intersect
+
+```ruby
+grant = declared.intersect(RobotLab::Capabilities.ceiling)
+```
+
+The effective grant. Per field:
+
+| Field | Rule |
+|-------|------|
+| `fs_read` / `fs_write` | A requested path survives only when it **is** a ceiling root or lives beneath one. Both sides are `File.expand_path`ed before comparison, so `~` and relative paths resolve first |
+| `network` | `declared && ceiling` — both must allow it |
+| `timeout` | The **smaller** of the two |
+| `trust` | The **declared** value, unchanged |
+
+Because the check is prefix-based on expanded paths, a ceiling of `["."]` grants
+nothing outside the working directory even if a skill asks for `/etc`.
+
+---
+
+## RobotLab::ScriptTool
+
+Factory module that turns an executable script into a `RobotLab::Tool`. All
+methods are module functions.
+
+### ScriptTool.from_path
+
+```ruby
+tool = RobotLab::ScriptTool.from_path(script_path, capabilities: nil, skill_dir: nil)
+# => RobotLab::Tool, or nil
+```
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `script_path` | `String`, `Pathname` | **required** | The script file |
+| `capabilities` | `Capabilities`, `nil` | `nil` → `Capabilities.new` | The skill's declared capabilities |
+| `skill_dir` | `String`, `nil` | `nil` → the script's own directory | Bundle root; always granted read access under Seatbelt |
+
+**Returns `nil`** when the file is not executable, logging
+`"ScriptTool: <basename> is not executable, skipping"` at `warn`. It never raises.
+
+The generated tool takes a single optional `args` string parameter, which is
+`Shellwords.split` and appended to `bash <script>`. Its name comes from
+[`derive_name`](#scripttoolderive_name) and its description from
+[`extract_description`](#scripttoolextract_description).
+
+### ScriptTool.executor
+
+```ruby
+RobotLab::ScriptTool.executor          # => #call, or nil (the default)
+RobotLab::ScriptTool.executor = obj    # any object responding to
+                                        # call(cmd, capabilities:, skill_dir:)
+```
+
+The extension point core exposes for confinement. `nil` by default — core has
+no sandboxing of its own. `robot_lab-sandbox`, when required, sets this to
+`RobotLab::Sandbox::Executor`, which handles `capabilities`/timeout/cleanup
+itself. See that gem's docs for what it does when installed.
+
+### ScriptTool.execute
+
+```ruby
+RobotLab::ScriptTool.execute(cmd, capabilities:, skill_dir:)  # => String
+```
+
+Run a command array and return its combined stdout+stderr, or an error string.
+Two paths:
+
+- **`executor` is `nil`** (the default) — `Open3.capture2e`, unconfined, **no timeout**.
+- **`executor` is set** — delegates entirely to `executor.call(cmd, capabilities:, skill_dir:)`.
+  Core no longer knows or cares what the executor does with `capabilities` or
+  how (or whether) it bounds execution time.
+
+### ScriptTool.format_result
+
+```ruby
+RobotLab::ScriptTool.format_result(output, status)  # => String
+```
+
+| `status` | Result |
+|----------|--------|
+| `nil` | `"Error (timed out):\n<output>"` |
+| success | `output` verbatim |
+| non-zero exit | `"Error (exit <N>):\n<output>"` |
+
+Failures come back as **text for the LLM**, not exceptions — the model sees the
+error and can adapt.
+
+### ScriptTool.derive_name
+
+```ruby
+RobotLab::ScriptTool.derive_name(Pathname.new("check-deploy.sh"))  # => "check_deploy"
+```
+
+Strips the final extension, replaces every run of non-alphanumerics with `_`, and
+trims leading/trailing underscores.
+
+### ScriptTool.extract_description
+
+```ruby
+RobotLab::ScriptTool.extract_description(path)  # => String
+```
+
+The first non-shebang comment line in the file, with leading `#` and whitespace
+removed. Falls back to `derive_name(path)` when there is no comment or the file
+cannot be read.
+
+```bash
+#!/usr/bin/env bash
+# Verifies a deployment's health before promoting it.   <- becomes the description
+```
+
+---
+
+## Confinement: robot_lab-sandbox
+
+`RobotLab::Sandbox`, `RobotLab::Sandbox::Seatbelt`, and `RobotLab::Sandbox::Null`
+used to live here; they now ship in the separate
+[`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox) gem, which
+core has no dependency on. Requiring it installs `RobotLab::Sandbox::Executor`
+as [`ScriptTool.executor`](#scripttoolexecutor):
+
+- `Sandbox.enabled?` — reads `config.sandbox.enabled` (default `false`).
+- `Sandbox.for(grant, skill_dir:, macos: macos?)` — picks `Sandbox::Seatbelt` on
+  macOS, `Sandbox::Null` (passthrough) elsewhere or for `trust: core` grants.
+- `Sandbox::Seatbelt` — generates a deny-by-default `sandbox-exec` profile from
+  the effective grant (`fs_read`/`fs_write`/`network`), wrapping the command as
+  `sandbox-exec -f <profile> <cmd...>`. `$HOME` is never implicitly readable.
+- `Sandbox::Null` — `wrap(cmd)` returns `cmd` unchanged; `cleanup` is a no-op.
+- `Sandbox::Executor` — the piece that plugs into core: intersects the skill's
+  `Capabilities` with `Capabilities.ceiling`, wraps and runs the command under
+  the chosen strategy, and bounds it with the grant's `timeout`
+  (`Process.kill('-TERM', ...)` on the process group on expiry).
+
+Full reference lives in that gem's own docs.
+
+---
+
+## See Also
+
+- [Using Tools: Skill Scripts and Sandboxing](../guides/using-tools.md#skill-scripts-and-sandboxing)
+- [Configuration: `sandbox:` section](../getting-started/configuration.md#skill-script-sandboxing-sandbox-section)
+- [robot_lab-sandbox](https://github.com/MadBomber/robot_lab-sandbox) — the optional confinement gem
+- [Robot: Skills](core/robot.md#skills) — template skills, the other meaning
+- [Tool](core/tool.md) — `Tool.create`, which `ScriptTool` builds on

data/docs/api/streaming/context.md

@@ -2,6 +2,12 @@
 
 Manages streaming event publishing with automatic sequencing, timestamping, and ID generation.
 
+> **Not wired into the framework.** No robot, network, task, or hook ever
+> constructs a `Streaming::Context` — `grep -rn "Streaming::" lib/` finds nothing
+> outside `lib/robot_lab/streaming/`. The class works, but it only publishes what
+> *you* hand it. For token streaming from a robot, use `on_content:` or the block
+> form of `run`; see the [Streaming overview](index.md#the-real-streaming-api).
+
 ## Class: `RobotLab::Streaming::Context`
 
 ```ruby
@@ -157,10 +163,20 @@ Create a new context that shares the same sequence counter as this context, but
 ### generate_part_id
 
 ```ruby
-context.generate_part_id  # => "part_run_1234_900123_a1b2c3d4"
+context.generate_part_id  # => "part_37ac1d49_815007_8f522876"
 ```
 
-Generate an OpenAI-compatible part ID (max 40 characters). Combines a truncated message ID, a timestamp suffix, and random hex.
+Generate an OpenAI-compatible part ID (max 40 characters), assembled as
+`"part_<msg>_<ts>_<rand>"`:
+
+| Segment | Source | Length |
+|---------|--------|--------|
+| `<msg>` | First 8 characters of **`message_id`** (not `run_id`) | 8 |
+| `<ts>` | Last 6 digits of the millisecond Unix timestamp | 6 |
+| `<rand>` | `SecureRandom.hex(4)` | 8 hex chars |
+
+Note this reads `message_id`, so two contexts sharing a message produce IDs with
+the same first segment.
 
 ### generate_step_id
 
@@ -168,7 +184,11 @@ Generate an OpenAI-compatible part ID (max 40 characters). Combines a truncated
 context.generate_step_id("text_output")  # => "publish-3:text_output"
 ```
 
-Generate a step ID for durable execution compatibility. Uses the current sequence number.
+Generate a step ID for durable execution compatibility, formatted as
+`"publish-<n>:<base_name>"`. It reads the counter with `current`, which does
+**not** increment: `<n>` is the sequence number of the most recently published
+event (`0` before anything has been published), so calling it repeatedly between
+publishes yields the same ID.
 
 **Parameters:**
 
@@ -206,10 +226,13 @@ context.publish_event(event: "text.delta", data: { delta: "world!" })
 context.publish_event(event: "run.completed", data: {})
 ```
 
-### Network with Child Contexts
+### Modelling a Multi-Robot Run with Child Contexts
+
+`RobotLab::Network` does not do any of this for you — the nesting below is
+something you would write by hand around your own orchestration.
 
 ```ruby
-# Network-level context
+# Parent context
 network_ctx = RobotLab::Streaming::Context.new(
   run_id: "net_run_1",
   message_id: "net_msg_1",

data/docs/api/streaming/index.md

@@ -1,10 +1,50 @@
 # Streaming
 
-Real-time event streaming during robot and network execution.
+A standalone event-publishing toolkit. **Not** the live streaming path.
+
+## Status: not wired in
+
+`RobotLab::Streaming::Context`, `Streaming::Events`, and
+`Streaming::SequenceCounter` exist and work, but **nothing in the framework uses
+them**. `grep -rn "Streaming::" lib/` returns zero hits outside
+`lib/robot_lab/streaming/` itself: no robot, network, task, or hook ever
+constructs a `Streaming::Context`, and no framework code publishes any of the
+events listed below. Enabling this module does not make a robot stream.
+
+Treat this as a set of building blocks you may drive yourself — a vocabulary of
+event names plus a sequencing/ID helper — if you are writing your own
+event-broadcast layer (a websocket relay, a SSE endpoint, an audit feed).
+
+### The real streaming API
+
+To actually receive tokens as a robot generates them, use `on_content:` and/or a
+block on `run`:
+
+```ruby
+# Constructor / RunConfig callback — fires on every run
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { print chunk.content }
+)
+
+# Or a block passed to run
+robot.run("Tell me a story") { |chunk| print chunk.content }
+```
+
+Each callback receives a `RubyLLM::Chunk`. Use `chunk.content` — there is no
+`chunk.text`. If both are supplied, both fire, with the stored `on_content`
+first. `on_content` is read from the robot's own config at construction time; a
+network-level `config:` does not supply it.
+
+The config key `streaming_enabled` has zero consumers in `lib/` and does nothing.
 
 ## Overview
 
-The streaming system provides structured event publishing during LLM execution. Events are emitted for run lifecycle, content deltas (token streaming), tool calls, and metadata updates. The system supports nested contexts for network-level orchestration where multiple robots execute within a single run.
+The module provides structured event publishing with automatic sequencing,
+timestamping, and ID generation. Event names cover run lifecycle, content deltas
+(token streaming), tool calls, and metadata updates, and contexts can be nested
+so a network-level run and its child robot runs share one monotonic sequence.
 
 ```ruby
 publish = ->(event) {
@@ -32,25 +72,26 @@ context.publish_event(event: "text.delta", data: { delta: "Hello" })
 |-----------|-------------|
 | [Context](context.md) | Manages streaming state, sequencing, and event publishing |
 | [Events](events.md) | Event type constants and classification helpers |
-
-Also used internally:
-
-| Component | Description |
-|-----------|-------------|
-| `SequenceCounter` | Thread-safe monotonic counter for event ordering |
+| `SequenceCounter` | Thread-safe monotonic counter for event ordering. Its only consumer is `Streaming::Context`, which is itself unused by the framework |
 
 ## Event Categories
 
+These are the names defined in `Streaming::Events`. They are constants and
+classification helpers only — no framework code emits any of them.
+
 | Category | Events | Description |
 |----------|--------|-------------|
 | Lifecycle | `run.started`, `run.completed`, `run.failed`, `run.interrupted` | Run-level state changes |
 | Steps | `step.started`, `step.completed`, `step.failed` | Durable execution steps |
 | Parts | `part.created`, `part.completed`, `part.failed` | Message composition parts |
-| Deltas | `text.delta`, `tool_call.arguments.delta`, `reasoning.delta`, `data.delta` | Token-level content streaming |
+| Deltas | `text.delta`, `tool_call.arguments.delta`, `tool_call.output.delta`, `reasoning.delta`, `data.delta` | Token-level content streaming |
 | HITL | `hitl.requested`, `hitl.resolved` | Human-in-the-loop events |
 | Metadata | `usage.updated`, `metadata.updated` | Token usage and metadata |
 | Terminal | `stream.ended` | End of stream signal |
 
+`DELTA_EVENTS` has five members — `tool_call.output.delta` is easy to miss.
+`ALL_EVENTS` has twenty.
+
 ## Event Structure
 
 Each published event is a hash with the following shape:
@@ -88,10 +129,14 @@ context.publish_event(event: "text.delta", data: { delta: "world!" })
 context.publish_event(event: "run.completed", data: {})
 ```
 
-### Nested Contexts for Networks
+### Nested Contexts
+
+Contexts can be nested to model a parent run with child runs sharing one
+sequence. Note that no `Network` creates these — you would build the hierarchy
+yourself.
 
 ```ruby
-# Parent context for the network run
+# Parent context for a run you are orchestrating
 network_context = RobotLab::Streaming::Context.new(
   run_id: "network_run_1",
   message_id: "msg_1",
@@ -108,3 +153,4 @@ robot_context.publish_event(event: "text.delta", data: { delta: "Response" })
 
 - [Context](context.md)
 - [Events](events.md)
+- [Robot](../core/robot.md) -- `on_content:`, and the block form of `run`, which is how streaming actually works