lyman 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10c9bb49a3623d7ef8179f561101dca35a940a5efb510a05b349c527a1141764
-  data.tar.gz: 6fa324e06604573e06c658991618a4715968ac097c3fff616abf0ba4f20a3f22
+  metadata.gz: d84a3588f59995354f5545ce07169904476a2ed0cff059405fd53f6af144cfab
+  data.tar.gz: ec3fcc387412a1b0281297ae725f9f0a80e9f7f4dabb49cd6255cb2754554d21
 SHA512:
-  metadata.gz: db9944dbe1f9258b65e9e682aedaf41cd4cdcba895a68e90e64390fbe0dfebb81d335df410338c3dd35ebfbbae553b592d7c642139a83e2c0cbdbf9d279360ff
-  data.tar.gz: 8ccdb31708d12bdbdaef0ff9438148165d7bdfe15dd19bcbc26f86cd600964fc046e9589185fc62824b55be427deff93287524b2f6e799a898533d58873ce6d1
+  metadata.gz: b89f9cbfa5a5529d00f5a8394e2eafcc0abc41ee6e4d96f218ce6637523de5113e8516040466c212a71d335963966bbb91f8eea7eb368efa738c6f2f2156546c
+  data.tar.gz: 359637ee13e913c77dfd144fde5e24763a6a2c4bce75cdac8677c033e13789a08223dcd79fe95065b4cdd15b33c86cdcde88b7295d339e13a35aa5a5f27d9cae

data/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+## 0.3.0
+
+The harness archetypes and immutable conversation release. Lyman now ships
+three archetype harnesses — one circuit, three shells — and adopts shifty
+0.6's frozen handoffs: `Conversation` became an immutable value. This is a
+breaking change for planted projects; see the migration notes below.
+
+### Breaking changes
+
+- **`Conversation` is an immutable value** (a `Data` subclass). Change is
+  expressed as new values: `with_user_message`, `with_assistant_message`,
+  `with_tool_result`, and `finish` replace `add_user_message`,
+  `add_assistant_message`, `add_tool_result`, and `finish!`, each returning
+  a new conversation. Shells rebind instead of mutating
+  (`conversation = pipeline.shift`). The round counter moved into
+  `with_assistant_message` — a round *is* one model reply — so a swapped-in
+  transport can no longer forget the runaway guard. Reasoning and design in
+  `docs/design/immutable-conversation.md`.
+- **shifty ~> 0.6 is required** (was 0.5). Shifty's default handoff policy
+  deeply freezes every value at a worker boundary; a worker that mutates
+  its input raises `Shifty::PolicyViolation`. The planted
+  `chat_completion` and `tool_execution` workers are rewritten
+  non-destructively and declare no policy escapes.
+- **The chat harness is renamed to the repl harness**: `harness/chat.rb` →
+  `harness/repl.rb`, display layer `harness/chat/` → `harness/repl/`.
+  Registry artifact names follow: `harness` → `repl_harness`,
+  `chat_style` → `repl_style`. Existing projects are unaffected in place —
+  harness artifacts are owned, `lyman update` never touches them, and
+  manifest entries unknown to this release are left alone — but a fresh
+  `lyman add` plants the new names at the new paths.
+
+### Migrating a planted project
+
+1. `bundle update shifty` (and take `gem "shifty", "~> 0.6"` in your
+   Gemfile).
+2. `lyman update` — refreshes the managed `conversation`,
+   `chat_completion`, and `tool_execution` modules (halting first, as
+   always, if you've modified them).
+3. Port your own harness and workers: `add_*` → `with_*`, `finish!` →
+   `finish`, and rebind shell state to what the pipeline returns. A
+   `Shifty::PolicyViolation` names the offending worker if you miss one.
+
+### Added
+
+- **The daemon archetype** (`lyman add daemon_harness`): launch once, loop
+  indefinitely on an inbound event stream — shipped as a stdlib-only,
+  line-per-event TCP listener (port 1216, the Lyman-alpha wavelength in
+  Ångströms), fresh conversation per event, tool calls logged by a spliced
+  side worker.
+- **The script archetype** (`lyman add script_harness`): work item from
+  ARGV or stdin at launch, one enqueue and one shift, final answer on
+  stdout, halt. No loop in the shell at all — repetition lives in the
+  pipeline.
+- **Opt-in artifacts as a registry concept matured**: `lyman new` plants
+  the repl; the daemon and script archetypes are a `lyman add` away, so a
+  narrow, purpose-built agent gets one shell shape, not three.
+- **The repl's display layer, one owned artifact per widget**
+  (`repl_style`, `think_filter`, `wait_spinner`, `round_printer`,
+  `tool_printer`), so ownership — and any drift `lyman diff` reports —
+  stays per-file. Its cli-ui/reline dependencies stay confined to
+  `harness/repl/`.
+- **Design notes**: `docs/design/harness-archetypes.md` (one circuit,
+  three shells) and `docs/design/immutable-conversation.md` (the shifty
+  0.6 adaptation).
+- **A documentation wiki** — [guided tour on GitHub](https://github.com/joelhelbling/lyman/wiki):
+  Getting Started, Core Concepts, the archetypes, and the generator CLI.
+  Sourced from `wiki/` in this repo and published with `wiki/publish.sh`.
+- Scaffolded guidance (`CLAUDE.md` / the `claude_skill` variant) now
+  carries five load-bearing facts — frozen handoffs joined the list — and
+  describes the archetypes.
+
+## 0.2.1
+
+- The chat harness display grew a proper face: cli-ui styling (colored
+  labels, glyphs), reline line editing and history at the prompt, a wait
+  spinner for prefill silence, a streamed dim preview of `<think>` blocks,
+  and one-line tool-call/result reporting. The scaffolded Gemfile gains
+  `cli-ui` and `reline` (display-layer only; drop them if you restyle).
+
+## 0.2.0
+
+### Added
+
+- **`claude_skill` artifact** (`lyman add claude_skill`): the scaffolded
+  CLAUDE.md guidance packaged as a Claude Code skill at
+  `.claude/skills/lyman/SKILL.md`, for projects that already have a
+  `CLAUDE.md` lyman shouldn't clobber. First **opt-in** artifact
+  (`optional:` in the registry): skipped by `new`, reached with `add`;
+  `lyman add claude_md` suggests it when refusing to overwrite an existing
+  file. `lyman list` labels opt-in artifacts.
+
+## 0.1.0
+
+Initial release: lyman as a **pure generator** (the shadcn/ui model) — the
+gem plants legible, manifest-tracked source into client projects and is
+never a runtime dependency.
+
+- The plantable library: `Conversation` (the item that flows through
+  pipelines) and the `chat_completion` (OpenAI-compatible, streaming +
+  blocking) and `tool_execution` workers.
+- The chat harness: the circuit pattern wired as one legible top-level
+  script, owned by the user from day one.
+- The generator CLI: `new`, `add`, `update`, `eject`, `diff`, `doctor`,
+  `list`, backed by a path-aware manifest (`.lyman/manifest.yml`) with a
+  pristine cache, three-tier `update` (pristine/modified/untracked),
+  eject-to-own with tombstones and upstream-change advisories, and a
+  pipeline smoke test (`doctor`) that needs no model server.

data/README.md

@@ -14,6 +14,8 @@ less margin for error than the frontier labs. Your one real edge is
 > series is also, fittingly, a sequence of discrete lines — like the stages of
 > a pipeline.
 
+![lyman new, then a first chat with a tool-using local model](demo/demo.gif)
+
 ## The idea
 
 An agent harness is a pipeline. Not as a metaphor — literally:
@@ -22,13 +24,13 @@ An agent harness is a pipeline. Not as a metaphor — literally:
 pipeline =
   source_worker { rounds.shift }                                             |
   Lyman::Workers.chat_completion(base_url:, model:, tools:)                  |
-  relay_worker { |c| c.finish! if c.pending_tool_calls.empty?; c }           |
+  relay_worker { |c| c.pending_tool_calls.empty? ? c.finish : c }            |
   Lyman::Workers.tool_execution(handlers)                                    |
   side_worker { |c| rounds << c unless c.finished? }                         |
   filter_worker { |c| c.finished? }
 ```
 
-That's not pseudocode — it's the working heart of [`harness/chat.rb`](harness/chat.rb),
+That's not pseudocode — it's the working heart of [`harness/repl.rb`](harness/repl.rb),
 a tool-using chat agent for local models. Every stage is a plain
 [shifty](https://github.com/joelhelbling/shifty) worker. Want logging? Splice
 in a `side_worker` — anywhere. Want a guardrail? A `filter_worker`. Want to
@@ -58,21 +60,26 @@ support (e.g. `qwen3.5`, `gemma4`, `mistral`).
 
 ```sh
 bundle install
-bundle exec ruby harness/chat.rb
+bundle exec ruby harness/repl.rb
 ```
 
 ```
 lyman ⇢ gemma4:latest @ http://localhost:11434/v1
 
 you> what time is it?
+
+gemma4:latest> ✻ The user wants the current time. I have a current_time tool…
+
   ⚙ current_time {}
+  ✓ current_time → 2026-07-08 18:13:29 EDT
 
-gemma4:latest> It's 9:25 PM on Friday, July 3rd.
+gemma4:latest> It's 6:13 PM on Wednesday, July 8th.
 ```
 
-That `⚙` line is a side worker showing you the model calling a tool — and the
-reply after it means two model round-trips completed inside a single pull on
-the pipeline. Point it elsewhere with `LYMAN_BASE_URL` and `LYMAN_MODEL`.
+The `✻` aside is a streamed preview of the model's thinking; the `⚙` and `✓`
+lines are side workers showing a tool call and its result — and the reply
+after them means two model round-trips completed inside a single pull on the
+pipeline. Point it elsewhere with `LYMAN_BASE_URL` and `LYMAN_MODEL`.
 
 ## How it works, briefly
 
@@ -84,6 +91,11 @@ the pipeline. Point it elsewhere with `LYMAN_BASE_URL` and `LYMAN_MODEL`.
   state plus a process: the conversation, a queue, and a deliberately boring
   loop. A human REPL is one shell; an autonomous email-triager is another.
   Lyman is turn-shaped, not chat-shaped.
+- **Three archetype harnesses prove it.** The same circuit ships inside
+  three shells: a **repl** (a human drives the loop), a **daemon** (loop
+  forever on an inbound event stream), and a **script** (take one work item
+  at launch, process it, halt). Only the shell differs — see
+  [docs/design/harness-archetypes.md](docs/design/harness-archetypes.md).
 - **The agentic loop is a circuit, not a special construct.** Shifty pipelines
   are strictly linear, so the model⇄tool cycle is built from stock parts: a
   source reading from a queue, a side worker re-enqueueing unfinished rounds,
@@ -98,6 +110,27 @@ the pipeline. Point it elsewhere with `LYMAN_BASE_URL` and `LYMAN_MODEL`.
 The longer story — mission, principles, architecture decisions, open
 questions — is in [docs/vision.md](docs/vision.md).
 
+## Documentation
+
+The **[wiki](https://github.com/joelhelbling/lyman/wiki)** is the guided
+tour:
+
+- [Getting Started](https://github.com/joelhelbling/lyman/wiki/Getting-Started) —
+  scaffold a project and talk to a local model in five minutes
+- [Core Concepts](https://github.com/joelhelbling/lyman/wiki/Core-Concepts) —
+  workers, the item, the shell, the circuit, and the sharp edges
+- [Harness Archetypes](https://github.com/joelhelbling/lyman/wiki/Harness-Archetypes) —
+  choosing between the [REPL](https://github.com/joelhelbling/lyman/wiki/The-REPL-Archetype),
+  [Daemon](https://github.com/joelhelbling/lyman/wiki/The-Daemon-Archetype), and
+  [Script](https://github.com/joelhelbling/lyman/wiki/The-Script-Archetype) shapes
+- [The Generator CLI](https://github.com/joelhelbling/lyman/wiki/The-Generator-CLI) —
+  `new`, `add`, `update`, `eject`, `diff`, `doctor`, and the manifest
+
+The wiki's source of truth is the [`wiki/`](wiki/) directory in this repo —
+documentation changes ride through pull requests, then publish with
+[`wiki/publish.sh`](wiki/publish.sh). For design *intent*, the
+[docs/](docs/) design notes remain authoritative.
+
 ## Is lyman a good fit for you?
 
 **Probably yes, if:**
@@ -148,11 +181,12 @@ touched at all: it's yours from day one.
 
 ## Status
 
-Early and moving. What exists today: the vision, circuit-pattern, and
-deployment design docs, the core `Conversation` item, chat-completion and
-tool-execution workers, a working tool-using chat harness against live local
-models, and the generator CLI (`new` / `add` / `update` / `eject` / `diff` /
-`doctor` / `list`) with a Minitest suite behind it. Published to
+Early and moving. What exists today: the vision, circuit-pattern,
+harness-archetypes, and deployment design docs, the core `Conversation` item,
+chat-completion and tool-execution workers, the three archetype harnesses
+(repl, daemon, script) working against live local models, and the generator
+CLI (`new` / `add` / `update` / `eject` / `diff` / `doctor` / `list`) with a
+Minitest suite behind it. Published to
 [rubygems.org](https://rubygems.org/gems/lyman) — install it with:
 
 ```sh
@@ -160,7 +194,7 @@ gem install lyman
 lyman new my-agent
 ```
 
-On deck: tool-call fan-out and a one-shot (non-REPL) harness.
+On deck: tool-call fan-out.
 
 ## License
 

data/docs/design/harness-archetypes.md

@@ -0,0 +1,153 @@
+# Design note: the harness archetypes — one circuit, three shells
+
+**Status:** accepted (shipped with the repl, daemon, and script harnesses)
+**Builds on:** [circuit-pattern.md](circuit-pattern.md) (the model⇄tool loop)
+and the shell concept in [../vision.md](../vision.md)
+
+## The claim these examples exist to prove
+
+The vision document makes a structural claim: lyman is **turn-shaped, not
+chat-shaped**. A human REPL is one shell; an autonomous email triager is
+another; *same architecture, different shells*. One example harness can't
+demonstrate that — a single example reads as "the way," and a chat example
+reads as "lyman is a chat framework."
+
+So lyman ships three harnesses. They are not three random examples; they are
+**archetypes** — the three answers to the two questions every agentic
+workflow must settle before any code is written:
+
+1. **Where do work items come from?** (a human at a prompt, an inbound event
+   stream, the launch itself)
+2. **When does the process end?** (when the human leaves, never, when the
+   item is done)
+
+Everything else — which model, which tools, what the items mean — is
+configuration *within* an archetype. The archetype is the shell shape.
+
+## The invariant: the circuit does not change
+
+Recall the two-part anatomy from the circuit-pattern note:
+
+- The **circuit** is the linear pipeline that runs one work item to
+  completion: source-from-queue → model call → finish-or-continue check →
+  tool execution → re-enqueue-if-unfinished → only-finished-items-escape.
+  N model⇄tool rounds happen inside a single `pipeline.shift`, driven by
+  shifty's own demand semantics.
+- The **shell** is the enclosing scope: state (the conversation, the `rounds`
+  queue) plus a driving process. Deliberately boring.
+
+Across all three shipped harnesses, **the circuit is the same pipeline**
+(the repl adds display side-workers; the daemon adds a logging side-worker;
+those are splices, not rewiring). What differs is entirely in the shell:
+
+|                        | REPL (`harness/repl.rb`) | Daemon (`harness/daemon.rb`) | Script (`harness/script.rb`) |
+|------------------------|--------------------------|------------------------------|------------------------------|
+| **Work items from**    | a human at a prompt      | an inbound event stream (socket, queue, webhook) | launch arguments or stdin |
+| **Driving process**    | `loop { read, enqueue, shift }` | `loop { accept, enqueue, shift, answer }` | no loop: enqueue, shift once, halt |
+| **Ends when**          | the human leaves (blank line, ctrl-c) | never (until killed)   | the one item is done         |
+| **Human in the loop**  | yes — the human *is* the supplier | no (unless spliced in) | no                           |
+| **Conversation state** | one conversation, accreting turn by turn | fresh conversation per event | one conversation, one turn |
+| **Output**             | streamed to the terminal as it happens | reply to the event's sender; log to stdout | final answer on stdout |
+| **Launched by**        | a person                 | an init system, `ruby harness/daemon.rb &` | cron, a Makefile, another script |
+
+That table *is* the design: three columns of shell decisions, zero rows that
+touch the circuit.
+
+## The archetypes
+
+### REPL — human-in-the-loop-as-driver
+
+The classic formula. The shell reads a line, enqueues the turn, shifts, and
+repeats until the human ends it. Because the same human sees every answer,
+the conversation **accretes**: the shell keeps one conversation binding
+across the whole session, extending it with `with_user_message` on the way
+into the circuit and rebinding to the finished turn that comes back
+(`Conversation` is an immutable value — see
+[immutable-conversation.md](immutable-conversation.md)).
+
+The repl is also where a display layer earns its keep — a human is watching,
+so the harness streams tokens, previews `<think>` blocks, and shows tool
+calls as they happen. All of that lives in `harness/repl/` (one widget per
+file, each an owned artifact), and its dependencies (cli-ui, reline) are
+confined there: delete the display layer and the circuit doesn't notice.
+
+### Daemon — launch once, loop on events
+
+The shell starts an event supplier and loops forever: accept an event,
+enqueue it, shift, deliver the answer back. No human is in the loop; the
+model runs on its own recognizance, bounded by the same `max_rounds` guard
+as every other harness. (A human *approval gate* can be spliced in as a side
+worker that blocks on whatever collaborator the shell provides — see
+"intervention" in the circuit-pattern note — but the archetype's default is
+autonomy.)
+
+The shipped daemon listens on a TCP socket, one line per event, because
+that's stdlib and demoable with `nc`. **The supplier is this archetype's
+variable**: a webhook server, an AMQP consumer, an IMAP poller, a filesystem
+watcher — all daemon harnesses, differing only in the few lines that turn
+"something arrived" into an enqueued work item. The circuit never knows
+where events come from; only the queue does.
+
+Each event gets a **fresh conversation** — a daemon's work items are
+independent, so context doesn't accrete across them unless you decide it
+should (a memory is a splice, not a default).
+
+### Script — one work item, then halt
+
+The shell is launched by something out of scope — cron, CI, a person who
+wants one answer — and the work item arrives *with the launch*: `ARGV` or
+stdin. Enqueue, shift once, print the final answer, exit. The exit code and
+stdout are the interface, because the caller is a program.
+
+The script archetype is the starkest demonstration that **repetition lives
+in the pipeline, not the shell**: there is no loop anywhere in the file, yet
+the model⇄tool circuit still runs as many rounds as the task needs, all
+inside the single `pipeline.shift`.
+
+## Shared sharp edges, per archetype
+
+The library's sharp edges (see CLAUDE.md) show up in each shell in a
+characteristic way — worth naming, because each archetype tempts a different
+mistake:
+
+- **The nil footgun** (a source returning `nil` ends the stream forever).
+  All three shells obey the same rule: *enqueue before you shift*. The repl
+  and daemon are tempted to shift inside their loops before anything
+  arrived; the script's straight-line shape makes the ordering obvious —
+  which is why it's the best archetype to read first.
+- **Runaway turns.** The repl has a human who would notice a model stuck in
+  tool-call loops; the daemon and script do not. The `runaway?` /
+  `max_rounds` guard on `Conversation` is load-bearing in exactly the
+  harnesses where nobody is watching.
+- **Blocking vs. streaming.** The repl streams (`on_delta`) because a human
+  is waiting; the daemon and script use the blocking transport because their
+  consumers want the finished answer, not tokens. Same
+  `Workers.chat_completion` seam either way.
+
+## Choosing an archetype
+
+Ask the two questions from the top:
+
+- A person supplies work items interactively → **repl**.
+- Events arrive on their own schedule, forever → **daemon**.
+- The work item is known at launch and the process should end → **script**.
+
+Then change the parts the archetype marks as variable: the system prompt,
+the tools, the supplier (daemon), the output channel (script). The circuit
+only needs rewiring when the *workflow* changes shape (approval gates,
+fan-out, multi-model routing) — and then it's the same stock parts,
+re-plumbed, per the circuit-pattern note.
+
+## Deployment notes
+
+- `lyman new` plants the **repl** — the archetype you can talk to sixty
+  seconds after scaffolding. The daemon and script are opt-in artifacts
+  (`lyman add daemon_harness`, `lyman add script_harness`): a narrow,
+  purpose-built agent wants one shell shape, not three files two of which
+  are dead weight.
+- All three are **owned from day one** — wiring scripts, never targets of
+  `lyman update`. Improvements to archetypes ship as new examples to
+  `add`/`diff` against, never as merges into your harness.
+- The daemon and script deliberately have **no display-layer dependencies**;
+  they are stdlib + the planted `lib/lyman` modules. Only the repl pulls in
+  cli-ui and reline, and only inside `harness/repl/`.

data/docs/design/immutable-conversation.md

@@ -0,0 +1,71 @@
+# Immutable Conversation: adapting to shifty 0.6 frozen handoffs
+
+Shifty 0.6.0 changed what crosses a worker boundary. Under the new default
+handoff policy (`:frozen`), every value a worker receives is deeply frozen
+via `Ractor.make_shareable` at intake; a task that mutates its input raises
+`Shifty::PolicyViolation` at the offending worker. Per-worker escape hatches
+exist (`policy: :isolated` for a private scratch copy, `policy: :shared` for
+raw pre-0.6 references), and a global opt-out reproduces 0.5 behavior.
+
+## The decision
+
+`Conversation` became an immutable value, and no worker declares a policy.
+This is shifty's own preferred migration path (rewrite non-destructively),
+and it wins on lyman's design razor — whatever lets a user see and change
+behavior faster:
+
+- **Policy declarations are the second paradigm.** A pipeline where some
+  workers carry `policy: :shared` and some don't makes handoff semantics a
+  per-stage thing a reader must track. With an immutable item, every handoff
+  means the same thing everywhere.
+- **Silent aliasing was the circuit's real risk.** The circuit re-enqueues
+  the item back into shell scope; a mutable conversation is shared between
+  the queue, the shell binding, and whatever a spliced-in worker holds onto.
+  Frozen handoffs turn that class of bug into an immediate, named error.
+- **`:shared` restores exactly the protection-free semantics 0.6 exists to
+  end** — the escape hatch stays reserved for genuinely uncopyable values
+  (IO handles, procs), which the conversation is not.
+
+## The shape
+
+`Conversation < Data.define(...)` — Ruby's stdlib immutable value, the
+idiom shifty's own docs recommend. `Data#with` allocates one new outer
+object and structurally shares unchanged members between old and new
+values; that sharing is safe precisely because handed-off values are
+frozen. The two mechanisms are a matched set, and the per-handoff freeze
+traversal only visits structure created since the last handoff, so the
+combination stays cheap.
+
+Consequences, visible in the code:
+
+- Mutators became `with_*` methods returning a new conversation:
+  `with_user_message`, `with_assistant_message`, `with_tool_result`, and
+  `finish` (no bang — nothing mutates). `Data#with` remains public for
+  splicing in custom state.
+- The round counter moved into `with_assistant_message`: a round *is* one
+  model reply, so counting it there means a swapped-in transport cannot
+  forget the runaway guard.
+- Workers hand off what they build: `chat_completion` and `tool_execution`
+  return `conversation.with_*(...)` results instead of returning a mutated
+  input. Their internal message assembly (streaming deltas accumulating
+  into a hash) is untouched — closure and local state stay freely mutable;
+  the freeze happens at handoff. "Mutable within, immutable between."
+- The shell rebinds instead of mutating: `harness/chat.rb` enqueues
+  `conversation.with_user_message(input)` and then does
+  `conversation = pipeline.shift`. Turn state flowing back to the shell is
+  now an explicit assignment sitting in the wiring script — state lives in
+  the shell's scope, visibly.
+
+## What to watch when adding workers
+
+- Never mutate the item; build a new one (`with_*`, `Data#with`, `merge`,
+  `+`). A `PolicyViolation` names the worker and object if you slip.
+- A builder that keeps a reference to what it handed off will find it
+  frozen — hand off snapshots (`dup`, `join`, `with(...)`), keep the live
+  accumulator private.
+- Unshareable values (IO, procs, lazy enumerators) cannot cross a default
+  boundary; if a worker must pass one, declare `policy: :shared` on that
+  worker and say why in a comment.
+- `Shifty::Testing.mutates_input?(worker, input)` (opt-in
+  `require "shifty/testing"`) is the mutation detector — use it when
+  vetting a worker whose task you don't fully control.

data/harness/daemon.rb

@@ -0,0 +1,119 @@
+#!/usr/bin/env ruby
+#
+# The daemon archetype: launch once, then loop on an inbound stream of
+# events, indefinitely. No human in the loop — each arriving event is a
+# work item, processed to completion and answered. One of three archetype
+# shells — repl, daemon, script — around the same circuit; see
+# docs/design/harness-archetypes.md.
+#
+# The shell: state + a process. The process is `loop { accept an event,
+# enqueue, shift, answer }` — the same enqueue-then-shift rhythm as the
+# repl, with a socket where the human used to be.
+#
+# The event supplier here is a line-per-event TCP listener, chosen because
+# it's stdlib and legible — try it with:
+#
+#   echo "what time is it?" | nc localhost 1216
+#
+# The supplier is this archetype's variable: swap the TCPServer for a
+# webhook server, a queue consumer, an IMAP poller — the circuit below
+# doesn't change, because the circuit never knows where events come from.
+# Only the source_worker's queue does.
+
+# require_relative, not the load path: these are files planted beside this
+# script, not the lyman gem.
+require_relative "../lib/lyman"
+require "socket"
+
+# This is a top-level wiring script by design; mixing the DSL into main
+# is the point, not an accident.
+include Shifty::DSL # standard:disable Style/MixinUsage
+
+$stdout.sync = true
+
+BASE_URL = ENV.fetch("LYMAN_BASE_URL", "http://localhost:11434/v1")
+MODEL = ENV.fetch("LYMAN_MODEL", "gemma4:latest")
+PORT = Integer(ENV.fetch("LYMAN_PORT", "1216")) # Lyman-alpha: 1216 Å
+
+# ── Tools: schema and handler side by side, guts on the outside ────────────
+TOOLS = {
+  "current_time" => {
+    schema: {
+      "type" => "function",
+      "function" => {
+        "name" => "current_time",
+        "description" => "Returns the current local date and time",
+        "parameters" => {"type" => "object", "properties" => {}, "required" => []}
+      }
+    },
+    handler: ->(_args) { Time.now.strftime("%Y-%m-%d %H:%M:%S %Z") }
+  }
+}
+
+schemas = TOOLS.values.map { |tool| tool[:schema] }
+handlers = TOOLS.transform_values { |tool| tool[:handler] }
+
+# ── Shell state ─────────────────────────────────────────────────────────────
+rounds = [] # the circuit's queue — visible right here, not smuggled
+
+# ── The circuit ─────────────────────────────────────────────────────────────
+# Identical to the script archetype's circuit, plus one logging side_worker —
+# with no human watching, observability is spliced in, not bolted on.
+pipeline =
+  source_worker { rounds.shift } |
+  Lyman::Workers.chat_completion(base_url: BASE_URL, model: MODEL, tools: schemas) |
+  relay_worker { |c|
+    (c.pending_tool_calls.empty? || c.runaway?) ? c.finish : c
+  } |
+  side_worker { |c|
+    c.pending_tool_calls.each do |call|
+      puts "  ⚙ #{call.dig("function", "name")} #{call.dig("function", "arguments")}"
+    end
+  } |
+  Lyman::Workers.tool_execution(handlers) |
+  side_worker { |c| rounds << c unless c.finished? } |
+  filter_worker { |c| c.finished? }
+
+# ── Shell process ───────────────────────────────────────────────────────────
+server = TCPServer.new(PORT)
+puts "lyman daemon ⇢ #{MODEL} @ #{BASE_URL}, listening on port #{PORT}"
+
+loop do
+  client = server.accept
+  event = begin
+    client.gets&.strip
+  rescue IOError, SystemCallError
+    nil # a client that hung up mid-line is not our problem
+  end
+
+  if event.nil? || event.empty?
+    client.close
+    next
+  end
+
+  puts "[#{Time.now.strftime("%H:%M:%S")}] event: #{event}"
+
+  # Each event is an independent work item, so it gets a fresh conversation —
+  # a daemon accretes no context across events unless you decide it should.
+  conversation = Lyman::Conversation.new(
+    system_prompt: "You are an event handler. Handle the incoming event and " \
+      "reply with the result only — plain text, no markdown, no commentary."
+  )
+
+  # Enqueue before shifting — never pull the source while the queue is empty
+  # (the nil footgun: a nil from a source ends the stream permanently).
+  # Conversation is an immutable value (shifty 0.6 freezes every handoff):
+  # with_user_message returns a new conversation, and the finished turn
+  # comes back from the pipeline.
+  rounds << conversation.with_user_message(event)
+  result = pipeline.shift
+
+  reply = result.last_assistant_content.to_s
+  puts "[#{Time.now.strftime("%H:%M:%S")}] reply: #{reply}"
+  client.puts reply
+  client.close
+rescue Interrupt
+  puts "\nshutting down"
+  server.close
+  break
+end

data/harness/repl/round_printer.rb

@@ -0,0 +1,43 @@
+require "cli/ui"
+require_relative "think_filter"
+require_relative "wait_spinner"
+
+# Streams one round's content to the terminal: a spinner while waiting on
+# the model, then the model label before the first visible text — so silent
+# rounds (pure tool calls) don't leave an empty prompt behind.
+class RoundPrinter
+  def initialize(label)
+    @label = label
+    @spinner = WaitSpinner.new
+  end
+
+  def start_round
+    @think = ThinkFilter.new
+    @printed = false
+    @spinner.start("waiting for #{@label}…")
+  end
+
+  def delta(text)
+    think, reply = @think.filter(text)
+    emit(think)
+    emit(reply)
+  end
+
+  def finish_round
+    @spinner.stop
+    think, reply = @think.flush
+    emit(think)
+    emit(reply)
+    puts if @printed
+  end
+
+  private
+
+  def emit(text)
+    return if text.empty?
+    @spinner.stop
+    print CLI::UI.fmt("\n{{magenta:#{@label}}}> ") unless @printed
+    @printed = true
+    print text
+  end
+end

data/harness/repl/style.rb

@@ -0,0 +1,13 @@
+require "cli/ui"
+
+# Styling codes used across streamed fragments, where CLI::UI.fmt can't help
+# (fmt resets at the end of each call; a think preview arrives in pieces).
+# Empty when piped, matching cli-ui's own no-tty behavior.
+TTY = $stdout.tty?
+GRAY = TTY ? CLI::UI.resolve_color(:gray).code : ""
+DIM = TTY ? "\e[2;3m" : "" # faint italic, for think previews
+RESET = TTY ? CLI::UI::Color::RESET.code : ""
+
+# Paint without CLI::UI.fmt so text we don't control (tool arguments and
+# results) can't be misread as {{markup}}.
+def gray(text) = "#{GRAY}#{text}#{RESET}"