robot_lab 0.3.0 → 0.3.1

data/docs/api/skills.md

@@ -1,423 +0,0 @@
-# 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

@@ -1,280 +0,0 @@
-# Streaming::Context
-
-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
-context = RobotLab::Streaming::Context.new(
-  run_id: "run_123",
-  message_id: "msg_456",
-  scope: "network",
-  publish: ->(event) { broadcast(event) }
-)
-
-context.publish_event(event: "text.delta", data: { delta: "Hello" })
-```
-
-## Constructor
-
-```ruby
-Context.new(
-  run_id:,
-  message_id:,
-  scope:,
-  publish:,
-  parent_run_id: nil,
-  sequence_counter: nil
-)
-```
-
-**Parameters:**
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `run_id` | `String` | required | Unique identifier for this run |
-| `message_id` | `String` | required | Current message identifier |
-| `scope` | `String`, `Symbol` | required | Context scope (e.g., `"network"`, `"robot"`) |
-| `publish` | `Proc` | required | Callback invoked with each event hash |
-| `parent_run_id` | `String`, `nil` | `nil` | Parent run identifier for nested contexts |
-| `sequence_counter` | `SequenceCounter`, `nil` | `nil` | Shared sequence counter (creates new one if nil) |
-
-## Attributes
-
-### run_id
-
-```ruby
-context.run_id  # => String
-```
-
-The unique run identifier for this context.
-
-### parent_run_id
-
-```ruby
-context.parent_run_id  # => String | nil
-```
-
-The parent run identifier. Set when this is a child context created by `create_child_context`.
-
-### message_id
-
-```ruby
-context.message_id  # => String
-```
-
-The current message identifier.
-
-### scope
-
-```ruby
-context.scope  # => String
-```
-
-The context scope (converted to string). Typically `"network"` or `"robot"`.
-
-## Methods
-
-### publish_event
-
-```ruby
-chunk = context.publish_event(event:, data: {})
-```
-
-Publish a streaming event. The event is wrapped in a chunk with automatic sequencing, timestamping, and context metadata injection.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `event` | `String` | Event type (e.g., `"text.delta"`, `"run.started"`) |
-| `data` | `Hash` | Event payload (default: `{}`) |
-
-**Returns:** The constructed event chunk hash.
-
-The chunk structure:
-
-```ruby
-{
-  event: "text.delta",
-  data: {
-    delta: "Hello",          # from data parameter
-    run_id: "run_123",       # injected from context
-    message_id: "msg_456",   # injected from context
-    scope: "robot"           # injected from context
-  },
-  timestamp: 1707900000000,  # millisecond Unix timestamp
-  sequence_number: 1,        # monotonically increasing
-  id: "publish-1:text.delta" # unique event ID
-}
-```
-
-If the publish callback raises an error, it is caught and logged as a warning via `RobotLab.config.logger`. The chunk is still returned.
-
-### create_child_context
-
-```ruby
-child = context.create_child_context(robot_run_id)
-```
-
-Create a child context for a nested robot execution. The child shares the same publish callback and sequence counter, ensuring events are ordered globally across the parent and child.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `robot_run_id` | `String` | Run ID for the child context |
-
-**Returns:** A new `Context` with:
-- `run_id` set to `robot_run_id`
-- `parent_run_id` set to the current context's `run_id`
-- `scope` set to `"robot"`
-- A new `message_id` (generated UUID)
-- Shared `sequence_counter` and `publish` callback
-
-### create_context_with_shared_sequence
-
-```ruby
-sibling = context.create_context_with_shared_sequence(
-  run_id: "run_789",
-  message_id: "msg_789",
-  scope: "robot"
-)
-```
-
-Create a new context that shares the same sequence counter as this context, but with different identifiers.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `run_id` | `String` | Run ID for the new context |
-| `message_id` | `String` | Message ID for the new context |
-| `scope` | `String` | Scope for the new context |
-
-**Returns:** A new `Context` sharing the sequence counter and publish callback.
-
-### generate_part_id
-
-```ruby
-context.generate_part_id  # => "part_37ac1d49_815007_8f522876"
-```
-
-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
-
-```ruby
-context.generate_step_id("text_output")  # => "publish-3:text_output"
-```
-
-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:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `base_name` | `String` | Base name for the step |
-
-### generate_message_id
-
-```ruby
-context.generate_message_id  # => "a1b2c3d4-..."
-```
-
-Generate a new UUID for use as a message identifier.
-
-## Examples
-
-### Basic Event Publishing
-
-```ruby
-publish = ->(event) {
-  puts "[#{event[:event]}] #{event[:data]}"
-}
-
-context = RobotLab::Streaming::Context.new(
-  run_id: SecureRandom.uuid,
-  message_id: SecureRandom.uuid,
-  scope: "robot",
-  publish: publish
-)
-
-context.publish_event(event: "run.started", data: { robot_name: "assistant" })
-context.publish_event(event: "text.delta", data: { delta: "Hello " })
-context.publish_event(event: "text.delta", data: { delta: "world!" })
-context.publish_event(event: "run.completed", data: {})
-```
-
-### 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
-# Parent context
-network_ctx = RobotLab::Streaming::Context.new(
-  run_id: "net_run_1",
-  message_id: "net_msg_1",
-  scope: "network",
-  publish: ->(e) { stream_to_client(e) }
-)
-
-network_ctx.publish_event(event: "run.started", data: {})
-
-# Robot 1 executes
-robot1_ctx = network_ctx.create_child_context("robot1_run_1")
-robot1_ctx.publish_event(event: "step.started", data: { robot: "classifier" })
-robot1_ctx.publish_event(event: "text.delta", data: { delta: "Category: billing" })
-robot1_ctx.publish_event(event: "step.completed", data: { robot: "classifier" })
-
-# Robot 2 executes (sequence numbers continue from robot 1)
-robot2_ctx = network_ctx.create_child_context("robot2_run_1")
-robot2_ctx.publish_event(event: "step.started", data: { robot: "responder" })
-robot2_ctx.publish_event(event: "text.delta", data: { delta: "I can help with that." })
-robot2_ctx.publish_event(event: "step.completed", data: { robot: "responder" })
-
-network_ctx.publish_event(event: "run.completed", data: {})
-```
-
-### Error-Safe Publishing
-
-```ruby
-# Errors in the publish callback are caught and logged,
-# so streaming failures do not interrupt execution.
-context = RobotLab::Streaming::Context.new(
-  run_id: "run_1",
-  message_id: "msg_1",
-  scope: "robot",
-  publish: ->(e) { raise "connection lost" }
-)
-
-# This does not raise -- the error is logged via RobotLab.config.logger
-chunk = context.publish_event(event: "text.delta", data: { delta: "test" })
-# chunk is still returned with the event data
-```
-
-## See Also
-
-- [Streaming Overview](index.md)
-- [Events](events.md)