lyman 0.2.0 → 0.3.0

data/lib/lyman/workers/tool_execution.rb

@@ -6,34 +6,37 @@ module Lyman
     extend Shifty::DSL
 
     # Relay worker: executes any tool calls pending on the conversation and
-    # appends their results. Acts only when the turn isn't already finished
-    # and the model has asked for tools; otherwise passes through.
+    # hands off a new conversation with their results appended. Acts only
+    # when the turn isn't already finished and the model has asked for
+    # tools; otherwise passes through.
     #
     # +handlers+ is a hash of tool name => callable taking a Hash of
     # arguments and returning something stringable.
     def self.tool_execution(handlers)
       relay_worker do |conversation|
-        unless conversation.finished?
-          conversation.pending_tool_calls.each do |tool_call|
-            name = tool_call.dig("function", "name")
-            args = parse_arguments(tool_call.dig("function", "arguments"))
-            handler = handlers[name]
+        # Fold results onto the accumulator while iterating the *original*
+        # conversation's pending calls: each with_tool_result appends a
+        # tool message, which empties pending_tool_calls on the new value.
+        conversation.pending_tool_calls.reduce(conversation) do |convo, tool_call|
+          break convo if convo.finished?
 
-            result =
-              if handler
-                begin
-                  handler.call(args).to_s
-                rescue => e
-                  "Tool #{name} raised #{e.class}: #{e.message}"
-                end
-              else
-                "Unknown tool: #{name}"
+          name = tool_call.dig("function", "name")
+          args = parse_arguments(tool_call.dig("function", "arguments"))
+          handler = handlers[name]
+
+          result =
+            if handler
+              begin
+                handler.call(args).to_s
+              rescue => e
+                "Tool #{name} raised #{e.class}: #{e.message}"
               end
+            else
+              "Unknown tool: #{name}"
+            end
 
-            conversation.add_tool_result(tool_call["id"], result)
-          end
+          convo.with_tool_result(tool_call["id"], result)
         end
-        conversation
       end
     end
 

data/templates/CLAUDE.md

@@ -2,17 +2,36 @@
 
 This project was scaffolded by [lyman](https://github.com/joelhelbling/lyman):
 an agentic harness built on the [shifty](https://github.com/joelhelbling/shifty)
-gem's pipeline-of-workers model. `harness/chat.rb` wires a model⇄tool loop
+gem's pipeline-of-workers model. `harness/repl.rb` wires a model⇄tool loop
 against any OpenAI-compatible chat completions endpoint (Ollama by default).
 
 ## Running it
 
-- `bundle install` — install dependencies (just `shifty` and `ostruct`; this
-  project has no runtime dependency on the `lyman` gem itself).
-- `ruby harness/chat.rb` — run the interactive chat harness. Defaults to
+- `bundle install` — install dependencies (`shifty`, `ostruct`, and `cli-ui`
+  for the harness's display layer; this project has no runtime dependency on
+  the `lyman` gem itself).
+- `ruby harness/repl.rb` — run the interactive repl harness. Defaults to
   Ollama at `http://localhost:11434/v1`; override with `LYMAN_MODEL` and
   `LYMAN_BASE_URL` env vars.
 
+## Harness archetypes
+
+Every lyman harness is the same model⇄tool circuit inside a different
+*shell* (state + a driving process). Three archetypes cover the shell
+shapes — see the [Harness Archetypes wiki page](https://github.com/joelhelbling/lyman/wiki/Harness-Archetypes):
+
+- **REPL** (`harness/repl.rb`, planted by default) — a human drives the
+  loop and ends it. One conversation accretes across turns.
+- **Daemon** (`lyman add daemon_harness`) — launch once, loop indefinitely
+  on an inbound event stream; no human in the loop. Fresh conversation per
+  event.
+- **Script** (`lyman add script_harness`) — launched by cron or on demand
+  with its work item in hand; processes it and halts. No loop in the shell
+  at all.
+
+To build a new harness, start from the archetype whose shell shape matches
+— the circuit rarely needs to change; the supplier of work items does.
+
 ## The managed/owned boundary
 
 Everything under the `Lyman::` namespace (`lib/lyman.rb`, `lib/lyman/`) is
@@ -23,27 +42,34 @@ which takes ownership explicitly rather than leaving it silently forked.
 `.lyman/manifest.yml` is the record of what's managed, what's owned, and what
 you've ejected; commit it.
 
-`harness/chat.rb` and everything outside `Lyman::` is **owned** — yours from
-day one, never touched by `lyman update`. Put your own workers in your own
-namespace or directory, not inside `lib/lyman/`.
+The harness scripts (`harness/*.rb`) and everything outside `Lyman::` are
+**owned** — yours from day one, never touched by `lyman update`. Put your own
+workers in your own namespace or directory, not inside `lib/lyman/`.
+
+## Five load-bearing facts
 
-## Four load-bearing facts
+1. **Frozen handoffs.** Shifty (0.6+) deep-freezes every value at a worker
+   boundary; a task that mutates its input raises `Shifty::PolicyViolation`.
+   `Conversation` is an immutable value: express change with its `with_*`
+   methods (a new conversation comes back) and rebind shell state to what
+   the pipeline returns — never mutate in place. Closure state inside a
+   worker stays freely mutable; only handed-off values freeze.
 
-1. **The nil-source footgun.** In shifty, a source returning `nil` ends the
+2. **The nil-source footgun.** In shifty, a source returning `nil` ends the
    stream permanently. If you're driving a pipeline off a queue, enqueue
    before you shift — never pull a source worker while its queue is empty.
 
-2. **The runaway-turn guard.** The model⇄tool circuit is bounded by
+3. **The runaway-turn guard.** The model⇄tool circuit is bounded by
    `Conversation#runaway?` / `max_rounds`. Keep that guard intact when
    rewiring the circuit; without it, a model that keeps calling tools never
    lets a turn end.
 
-3. **Item-as-control discipline.** An item may tell a worker *whether* to
+4. **Item-as-control discipline.** An item may tell a worker *whether* to
    act, never *which of several things* to do. A worker that switches
    between jobs based on item state is the anti-pattern to avoid
    (multi-way dispatch) — split it into stages, or use a splitter, instead.
 
-4. **Wire vs. conversation.** Reasoning/thinking content stays on messages in
+5. **Wire vs. conversation.** Reasoning/thinking content stays on messages in
    the `Conversation` for observability, but `Workers.wire_messages` strips
    it before anything goes out over the wire. Preserve that separation if
    you touch message handling.

data/templates/Gemfile

@@ -1,4 +1,7 @@
 source "https://rubygems.org"
 
-gem "shifty"
+gem "shifty", "~> 0.6" # handoff immutability: values are frozen at worker boundaries
 gem "ostruct" # shifty dependency; no longer a default gem as of ruby 4.0
+# Used only by harness/repl.rb's display layer; drop them if you restyle.
+gem "cli-ui"
+gem "reline"

data/templates/SKILL.md

@@ -1,23 +1,41 @@
 ---
 name: lyman
-description: Guidance for working in a lyman-scaffolded agentic harness — the pipeline-of-workers model, the managed/owned boundary, and lyman's sharp edges. Use when reading or changing the harness (harness/chat.rb), anything under lib/lyman/, or when running lyman CLI commands (add, update, eject, diff, doctor).
+description: Guidance for working in a lyman-scaffolded agentic harness — the pipeline-of-workers model, the harness archetypes, the managed/owned boundary, and lyman's sharp edges. Use when reading or changing a harness script (harness/*.rb), anything under lib/lyman/, or when running lyman CLI commands (add, update, eject, diff, doctor).
 ---
 
 # Working in a lyman project
 
 This project was scaffolded by [lyman](https://github.com/joelhelbling/lyman):
 an agentic harness built on the [shifty](https://github.com/joelhelbling/shifty)
-gem's pipeline-of-workers model. `harness/chat.rb` wires a model⇄tool loop
+gem's pipeline-of-workers model. `harness/repl.rb` wires a model⇄tool loop
 against any OpenAI-compatible chat completions endpoint (Ollama by default).
 
 ## Running it
 
 - `bundle install` — install dependencies (just `shifty` and `ostruct`; this
   project has no runtime dependency on the `lyman` gem itself).
-- `ruby harness/chat.rb` — run the interactive chat harness. Defaults to
+- `ruby harness/repl.rb` — run the interactive repl harness. Defaults to
   Ollama at `http://localhost:11434/v1`; override with `LYMAN_MODEL` and
   `LYMAN_BASE_URL` env vars.
 
+## Harness archetypes
+
+Every lyman harness is the same model⇄tool circuit inside a different
+*shell* (state + a driving process). Three archetypes cover the shell
+shapes — see the [Harness Archetypes wiki page](https://github.com/joelhelbling/lyman/wiki/Harness-Archetypes):
+
+- **REPL** (`harness/repl.rb`, planted by default) — a human drives the
+  loop and ends it. One conversation accretes across turns.
+- **Daemon** (`lyman add daemon_harness`) — launch once, loop indefinitely
+  on an inbound event stream; no human in the loop. Fresh conversation per
+  event.
+- **Script** (`lyman add script_harness`) — launched by cron or on demand
+  with its work item in hand; processes it and halts. No loop in the shell
+  at all.
+
+To build a new harness, start from the archetype whose shell shape matches
+— the circuit rarely needs to change; the supplier of work items does.
+
 ## The managed/owned boundary
 
 Everything under the `Lyman::` namespace (`lib/lyman.rb`, `lib/lyman/`) is
@@ -28,27 +46,34 @@ which takes ownership explicitly rather than leaving it silently forked.
 `.lyman/manifest.yml` is the record of what's managed, what's owned, and what
 you've ejected; commit it.
 
-`harness/chat.rb` and everything outside `Lyman::` is **owned** — yours from
-day one, never touched by `lyman update`. Put your own workers in your own
-namespace or directory, not inside `lib/lyman/`.
+The harness scripts (`harness/*.rb`) and everything outside `Lyman::` are
+**owned** — yours from day one, never touched by `lyman update`. Put your own
+workers in your own namespace or directory, not inside `lib/lyman/`.
+
+## Five load-bearing facts
 
-## Four load-bearing facts
+1. **Frozen handoffs.** Shifty (0.6+) deep-freezes every value at a worker
+   boundary; a task that mutates its input raises `Shifty::PolicyViolation`.
+   `Conversation` is an immutable value: express change with its `with_*`
+   methods (a new conversation comes back) and rebind shell state to what
+   the pipeline returns — never mutate in place. Closure state inside a
+   worker stays freely mutable; only handed-off values freeze.
 
-1. **The nil-source footgun.** In shifty, a source returning `nil` ends the
+2. **The nil-source footgun.** In shifty, a source returning `nil` ends the
    stream permanently. If you're driving a pipeline off a queue, enqueue
    before you shift — never pull a source worker while its queue is empty.
 
-2. **The runaway-turn guard.** The model⇄tool circuit is bounded by
+3. **The runaway-turn guard.** The model⇄tool circuit is bounded by
    `Conversation#runaway?` / `max_rounds`. Keep that guard intact when
    rewiring the circuit; without it, a model that keeps calling tools never
    lets a turn end.
 
-3. **Item-as-control discipline.** An item may tell a worker *whether* to
+4. **Item-as-control discipline.** An item may tell a worker *whether* to
    act, never *which of several things* to do. A worker that switches
    between jobs based on item state is the anti-pattern to avoid
    (multi-way dispatch) — split it into stages, or use a splitter, instead.
 
-4. **Wire vs. conversation.** Reasoning/thinking content stays on messages in
+5. **Wire vs. conversation.** Reasoning/thinking content stays on messages in
    the `Conversation` for observability, but `Workers.wire_messages` strips
    it before anything goes out over the wire. Preserve that separation if
    you touch message handling.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lyman
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Joel Helbling
@@ -13,16 +13,16 @@ dependencies:
   name: shifty
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
@@ -58,13 +58,23 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - docs/design/circuit-pattern.md
 - docs/design/deployment.md
+- docs/design/harness-archetypes.md
+- docs/design/immutable-conversation.md
 - docs/vision.md
 - exe/lyman
-- harness/chat.rb
+- harness/daemon.rb
+- harness/repl.rb
+- harness/repl/round_printer.rb
+- harness/repl/style.rb
+- harness/repl/think_filter.rb
+- harness/repl/tool_printer.rb
+- harness/repl/wait_spinner.rb
+- harness/script.rb
 - lib/lyman.rb
 - lib/lyman/cli.rb
 - lib/lyman/cli/commands/add.rb
@@ -91,6 +101,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/joelhelbling/lyman
+  changelog_uri: https://github.com/joelhelbling/lyman/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib

data/harness/chat.rb

@@ -1,244 +0,0 @@
-#!/usr/bin/env ruby
-#
-# The shell: state + a process. Deliberately boring.
-#
-# This file is the one legible wiring script — the circuit pattern from
-# docs/design/circuit-pattern.md, wired filter-in: one `pipeline.shift`
-# per turn, with all model⇄tool rounds happening inside the call.
-#
-# Everything the model does streams to the terminal as it happens —
-# pre-tool narration, tool calls, the final answer. Fitting the display
-# to the model (like hiding a <think> block) is this shell's job, not
-# the library's.
-
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "lyman"
-
-# 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")
-
-# ── 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] }
-
-# ── Display: fitting this harness to its models ─────────────────────────────
-
-# Thinking models prefix replies with <think>...</think> (the worker
-# normalizes separate-reasoning-field servers to the same convention). When
-# the reply arrives one fragment at a time we can't regex the whole thing, so
-# this streams a short preview of the thinking — the first few lines — then
-# elides the rest, closing with "...</think>" once the model stops thinking.
-class ThinkFilter
-  OPEN = "<think>"
-  CLOSE = "</think>"
-  SNIPPET_LINES = 3
-  SNIPPET_CHARS = 240 # think blocks are often one long unwrapped paragraph
-
-  def initialize
-    @state = :start
-    @buffer = +""
-    @lines = 0
-    @chars = 0
-    @truncated = false
-  end
-
-  # Returns the printable portion of this fragment.
-  def filter(fragment)
-    @buffer << fragment
-    case @state
-    when :start then filter_start
-    when :thinking then filter_thinking
-    when :after_think then filter_after_think
-    when :passing then take_buffer
-    end
-  end
-
-  # Call when the message is complete: releases anything still held back
-  # (e.g. a reply that was nothing but "<thin"), and closes a think block
-  # the model never closed itself.
-  def flush
-    case @state
-    when :start then take_buffer
-    when :thinking then (@truncated ? "..." : "") + CLOSE
-    else ""
-    end
-  end
-
-  private
-
-  def take_buffer
-    out = @buffer
-    @buffer = +""
-    out
-  end
-
-  def filter_start
-    if @buffer.start_with?(OPEN)
-      @state = :thinking
-      @buffer = @buffer[OPEN.length..]
-      OPEN + filter_thinking
-    elsif OPEN.start_with?(@buffer)
-      "" # could still become <think>; wait for more
-    else
-      @state = :passing
-      take_buffer
-    end
-  end
-
-  def filter_thinking
-    if (idx = @buffer.index(CLOSE))
-      thought = @buffer[0...idx]
-      @buffer = @buffer[(idx + CLOSE.length)..]
-      @state = :after_think
-      snippet(thought) + (@truncated ? "..." : "") + CLOSE + "\n\n" + filter_after_think
-    else
-      # Keep any tail that could be the start of CLOSE split across
-      # fragments; preview the rest.
-      keep = partial_close_suffix
-      thought = @buffer[0, @buffer.length - keep.length]
-      @buffer = keep
-      snippet(thought)
-    end
-  end
-
-  # The leading portion of the thought that fits the preview budget.
-  def snippet(text)
-    return "" if @truncated
-    out = +""
-    text.each_char do |ch|
-      if @chars >= SNIPPET_CHARS || (ch == "\n" && @lines >= SNIPPET_LINES - 1)
-        @truncated = true
-        break
-      end
-      out << ch
-      @chars += 1
-      @lines += 1 if ch == "\n"
-    end
-    out
-  end
-
-  # We print "</think>\n\n" ourselves, so swallow the model's own
-  # whitespace between the close tag and the reply.
-  def filter_after_think
-    stripped = @buffer.lstrip
-    if stripped.empty?
-      @buffer = +""
-      ""
-    else
-      @state = :passing
-      @buffer = stripped
-      take_buffer
-    end
-  end
-
-  def partial_close_suffix
-    (1...CLOSE.length).reverse_each do |len|
-      tail = @buffer[-len, len]
-      return tail if tail && CLOSE.start_with?(tail)
-    end
-    +""
-  end
-end
-
-# Streams one round's content to the terminal, printing 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
-  end
-
-  def start_round
-    @filter = ThinkFilter.new
-    @printed = false
-  end
-
-  def delta(text)
-    emit(@filter.filter(text))
-  end
-
-  def finish_round
-    emit(@filter.flush)
-    puts if @printed
-  end
-
-  private
-
-  def emit(text)
-    return if text.empty?
-    print "\n#{@label}> " unless @printed
-    @printed = true
-    print text
-  end
-end
-
-# ── Shell state ─────────────────────────────────────────────────────────────
-conversation = Lyman::Conversation.new(
-  system_prompt: "You are a helpful assistant. Keep replies brief."
-)
-rounds = [] # the circuit's queue — visible right here, not smuggled
-printer = RoundPrinter.new(MODEL)
-
-# ── The circuit ─────────────────────────────────────────────────────────────
-pipeline =
-  source_worker { rounds.shift } |
-  side_worker { |_c| printer.start_round } |
-  Lyman::Workers.chat_completion(
-    base_url: BASE_URL, model: MODEL, tools: schemas,
-    on_delta: printer.method(:delta)
-  ) |
-  side_worker { |_c| printer.finish_round } |
-  relay_worker { |c|
-    c.finish! if c.pending_tool_calls.empty? || c.runaway?
-    c
-  } |
-  side_worker do |c|
-    unless c.finished?
-      c.pending_tool_calls.each do |tc|
-        puts "  ⚙ #{tc.dig("function", "name")} #{tc.dig("function", "arguments")}"
-      end
-    end
-  end |
-  Lyman::Workers.tool_execution(handlers) |
-  side_worker { |c| rounds << c unless c.finished? } |
-  filter_worker { |c| c.finished? }
-
-# ── Shell process ───────────────────────────────────────────────────────────
-puts <<~PREAMBLE
-  lyman ⇢ #{MODEL} @ #{BASE_URL}
-
-    exit:      blank line or ctrl-d
-    model:     LYMAN_MODEL=qwen3.5:2b #{$PROGRAM_NAME}
-    endpoint:  LYMAN_BASE_URL=http://localhost:1234/v1 #{$PROGRAM_NAME}
-    tools:     #{TOOLS.keys.join(", ")} — a ⚙ line appears when the model calls one
-
-PREAMBLE
-
-loop do
-  print "\nyou> "
-  input = $stdin.gets&.strip
-  break if input.nil? || input.empty?
-
-  rounds << conversation.add_user_message(input)
-  pipeline.shift
-end