lyman 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42c4c9146ed53714fa0725775e91ffcbc599e485d652e84d483dedca2f47e047
-  data.tar.gz: e17d5dde1e338e8bae43cb97f5633b0cd4e24e06d66535bafdd2ff74319c9764
+  metadata.gz: 10c9bb49a3623d7ef8179f561101dca35a940a5efb510a05b349c527a1141764
+  data.tar.gz: 6fa324e06604573e06c658991618a4715968ac097c3fff616abf0ba4f20a3f22
 SHA512:
-  metadata.gz: 48c20fb9bb06c5f685b47491cc3d96cf33e7835b7b44bc1723bd87feec82a75d334b923a38c5d5838595bba31697e958e150dad4a5305e113edb454bcfd53e17
-  data.tar.gz: 26e9984e59ddc9722cb50bac1a3567cf9c424367c8dbed5e48bbf6b47fe3051052c59cd9e24a83fd5c7b49a81f056b2b256de89dda000c92798d536e072a8d5f
+  metadata.gz: db9944dbe1f9258b65e9e682aedaf41cd4cdcba895a68e90e64390fbe0dfebb81d335df410338c3dd35ebfbbae553b592d7c642139a83e2c0cbdbf9d279360ff
+  data.tar.gz: 8ccdb31708d12bdbdaef0ff9438148165d7bdfe15dd19bcbc26f86cd600964fc046e9589185fc62824b55be427deff93287524b2f6e799a898533d58873ce6d1

data/README.md

@@ -152,9 +152,15 @@ 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. Not yet published to
-rubygems.org — for now, run it from a checkout. On deck: publishing the gem,
-tool-call fan-out, and a one-shot (non-REPL) harness.
+`doctor` / `list`) with a Minitest suite behind it. Published to
+[rubygems.org](https://rubygems.org/gems/lyman) — install it with:
+
+```sh
+gem install lyman
+lyman new my-agent
+```
+
+On deck: tool-call fan-out and a one-shot (non-REPL) harness.
 
 ## License
 

data/docs/design/deployment.md

@@ -150,7 +150,12 @@ Three channels, ordered by reach:
    `AGENTS.md`) as a first-class artifact carrying the load-bearing facts: the
    nil-source footgun, the runaway-turn guard, item-as-control discipline,
    wire-vs-conversation separation. Highest-value channel: works with any
-   coding agent, zero install steps, travels with the code.
+   coding agent, zero install steps, travels with the code. For projects that
+   already have a `CLAUDE.md` lyman shouldn't clobber, the same guidance
+   ships as an opt-in Claude Code skill (`lyman add claude_skill` plants
+   `.claude/skills/lyman/SKILL.md`); `lyman add claude_md` points there when
+   it refuses to overwrite an existing file. Opt-in artifacts (`optional:` in
+   the registry) are skipped by `new` and reached with `add`.
 2. **A Claude plugin marketplace** in the `joelhelbling/lyman` repo, for
    richer *procedures* — e.g. a skill that knows how to wire a new tool worker
    correctly, or how to read a stalled pipeline. Skills earn their keep when

data/harness/chat.rb

@@ -42,15 +42,40 @@ schemas = TOOLS.values.map { |tool| tool[:schema] }
 handlers = TOOLS.transform_values { |tool| tool[:handler] }
 
 # ── Display: fitting this harness to its models ─────────────────────────────
+# Everything from here to "Shell state" is presentation. Its dependencies —
+# cli-ui for color and glyphs, reline (stdlib) for prompt line-editing and
+# history — are confined to this section; restyle or delete freely without
+# touching the circuit.
+require "cli/ui"
+require "reline"
+
+# 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}"
 
 # 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.
+# this streams a short preview of the thinking — the first few lines,
+# rendered as a dim "✻ …" aside rather than the literal tags — then elides
+# the rest once the model stops thinking.
+#
+# Emits [think_text, reply_text] pairs. Both stream straight to the terminal
+# today, but the split is the seam for reply-side processing (a markdown
+# renderer, say — mind that anything buffering the reply trades away its
+# token-by-token streaming, which is why this harness doesn't ship one).
 class ThinkFilter
   OPEN = "<think>"
   CLOSE = "</think>"
+  MARK = "✻ "
   SNIPPET_LINES = 3
   SNIPPET_CHARS = 240 # think blocks are often one long unwrapped paragraph
 
@@ -62,25 +87,26 @@ class ThinkFilter
     @truncated = false
   end
 
-  # Returns the printable portion of this fragment.
+  # Returns the printable portion of this fragment as a
+  # [think_text, reply_text] pair (either may be empty).
   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
+    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.
+  # (e.g. a reply that was nothing but "<thin"), and closes out the styling
+  # of a think block the model never closed itself.
   def flush
     case @state
-    when :start then take_buffer
-    when :thinking then (@truncated ? "..." : "") + CLOSE
-    else ""
+    when :start then ["", take_buffer]
+    when :thinking then [(@truncated ? "…" : "") + RESET, ""]
+    else ["", ""]
     end
   end
 
@@ -96,12 +122,13 @@ class ThinkFilter
     if @buffer.start_with?(OPEN)
       @state = :thinking
       @buffer = @buffer[OPEN.length..]
-      OPEN + filter_thinking
+      think, reply = filter_thinking
+      [DIM + MARK + think, reply]
     elsif OPEN.start_with?(@buffer)
-      "" # could still become <think>; wait for more
+      ["", ""] # could still become <think>; wait for more
     else
       @state = :passing
-      take_buffer
+      ["", take_buffer]
     end
   end
 
@@ -110,14 +137,14 @@ class ThinkFilter
       thought = @buffer[0...idx]
       @buffer = @buffer[(idx + CLOSE.length)..]
       @state = :after_think
-      snippet(thought) + (@truncated ? "..." : "") + CLOSE + "\n\n" + filter_after_think
+      [snippet(thought) + (@truncated ? "…" : "") + RESET + "\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)
+      [snippet(thought), ""]
     end
   end
 
@@ -137,8 +164,8 @@ class ThinkFilter
     out
   end
 
-  # We print "</think>\n\n" ourselves, so swallow the model's own
-  # whitespace between the close tag and the reply.
+  # We end the think preview with "\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?
@@ -160,25 +187,59 @@ class ThinkFilter
   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.
+# The silence between sending a prompt and the first streamed token can be
+# long on a local model (prefill). cli-ui's spinner owns the calling thread
+# for the duration of a block, which can't express "spin until the first
+# delta arrives" — so this is the one hand-rolled widget: a background
+# spinner with a stop method. Quiet when output is piped.
+class WaitSpinner
+  FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏]
+
+  def start(label)
+    return unless TTY
+    stop
+    @thread = Thread.new do
+      FRAMES.cycle do |frame|
+        print "\r#{GRAY}#{frame} #{label}#{RESET}"
+        sleep 0.08
+      end
+    end
+  end
+
+  def stop
+    return unless @thread
+    @thread.kill.join
+    @thread = nil
+    print "\r\e[K" # erase the spinner line
+  end
+end
+
+# 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
-    @filter = ThinkFilter.new
+    @think = ThinkFilter.new
     @printed = false
+    @spinner.start("waiting for #{@label}…")
   end
 
   def delta(text)
-    emit(@filter.filter(text))
+    think, reply = @think.filter(text)
+    emit(think)
+    emit(reply)
   end
 
   def finish_round
-    emit(@filter.flush)
+    @spinner.stop
+    think, reply = @think.flush
+    emit(think)
+    emit(reply)
     puts if @printed
   end
 
@@ -186,18 +247,56 @@ class RoundPrinter
 
   def emit(text)
     return if text.empty?
-    print "\n#{@label}> " unless @printed
+    @spinner.stop
+    print CLI::UI.fmt("\n{{magenta:#{@label}}}> ") unless @printed
     @printed = true
     print text
   end
 end
 
+# Prints tool activity around the execution stage: the calls the model
+# requested on the way in, a ✓-and-result line on the way out. Results are
+# summarized to one line here — the full text is on the conversation, where
+# the model (and any logging side-worker) sees it.
+class ToolPrinter
+  RESULT_WIDTH = 60
+
+  def calls(conversation)
+    conversation.pending_tool_calls.each do |tool_call|
+      puts gray("  ⚙ #{tool_call.dig("function", "name")} #{tool_call.dig("function", "arguments")}")
+    end
+  end
+
+  def results(conversation)
+    messages = conversation.messages
+    request = messages.rindex { |m| m["role"] == "assistant" }
+    return unless request
+    names = (messages[request]["tool_calls"] || [])
+      .to_h { |tc| [tc["id"], tc.dig("function", "name")] }
+    messages[(request + 1)..].each do |message|
+      next unless message["role"] == "tool"
+      summary = gray("#{names[message["tool_call_id"]]} → #{summarize(message["content"])}")
+      puts "  #{CLI::UI.fmt("{{v}}")} #{summary}"
+    end
+  end
+
+  private
+
+  def summarize(text)
+    line = text.to_s.gsub(/\s+/, " ").strip
+    (line.length > RESULT_WIDTH) ? "#{line[0, RESULT_WIDTH - 1]}…" : line
+  end
+end
+
 # ── Shell state ─────────────────────────────────────────────────────────────
 conversation = Lyman::Conversation.new(
-  system_prompt: "You are a helpful assistant. Keep replies brief."
+  system_prompt: "You are a helpful assistant. Keep replies brief. " \
+    "Your replies are printed verbatim in a plain-text terminal: write prose, " \
+    "and avoid markdown and LaTeX markup."
 )
 rounds = [] # the circuit's queue — visible right here, not smuggled
 printer = RoundPrinter.new(MODEL)
+tool_printer = ToolPrinter.new
 
 # ── The circuit ─────────────────────────────────────────────────────────────
 pipeline =
@@ -212,31 +311,36 @@ pipeline =
     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 |
+  side_worker { |c| tool_printer.calls(c) unless c.finished? } |
   Lyman::Workers.tool_execution(handlers) |
+  side_worker { |c| tool_printer.results(c) unless c.finished? } |
   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
+puts CLI::UI.fmt("{{bold:lyman}} ⇢ {{magenta:#{MODEL}}} @ {{blue:#{BASE_URL}}}")
+puts
+puts gray(<<~HINTS.gsub(/^/, "  "))
+  exit:                 blank line, ctrl-c, or ctrl-d
+  change the model:     LYMAN_MODEL=qwen3.5:2b #{$PROGRAM_NAME}
+  change the endpoint:  LYMAN_BASE_URL=http://localhost:1234/v1 #{$PROGRAM_NAME}
+  available tools:      #{TOOLS.keys.join(", ")} — a ⚙ line appears when the model calls one
+HINTS
 
 loop do
-  print "\nyou> "
-  input = $stdin.gets&.strip
+  puts
+  # Reline gives the prompt line editing and history, but emits screen-
+  # redraw escapes even when input is piped — so scripted runs get gets.
+  input = begin
+    if $stdin.tty?
+      Reline.readline(CLI::UI.fmt("{{cyan:you}}> "), true)&.strip
+    else
+      print "you> "
+      $stdin.gets&.strip
+    end
+  rescue Interrupt
+    nil # ctrl-c leaves like ctrl-d, not with a stack trace
+  end
   break if input.nil? || input.empty?
 
   rounds << conversation.add_user_message(input)

data/lib/lyman/cli/commands/add.rb

@@ -31,8 +31,13 @@ module Lyman
             end
           else
             if File.exist?(dest) && !force
-              raise Thor::Error, "#{dest} already exists and isn't tracked by lyman. " \
+              message = "#{dest} already exists and isn't tracked by lyman. " \
                 "Move it aside, or run `lyman add #{name} --force` to overwrite it."
+              if (alt = spec[:alternative])
+                message += " Or plant `lyman add #{alt}` instead, " \
+                  "which leaves #{spec[:dest]} untouched."
+              end
+              raise Thor::Error, message
             end
           end
 

data/lib/lyman/cli/commands/new.rb

@@ -19,7 +19,7 @@ module Lyman
           FileUtils.mkdir_p(project_root)
 
           manifest = Manifest.load(project_root)
-          Registry::ARTIFACTS.each do |artifact_name, spec|
+          Registry.default.each do |artifact_name, spec|
             plant(manifest, artifact_name, spec, project_root)
           end
           manifest.save

data/lib/lyman/cli/registry.rb

@@ -42,13 +42,26 @@ module Lyman
           source: "templates/CLAUDE.md",
           dest: "CLAUDE.md",
           role: :owned,
+          alternative: "claude_skill",
           description: "Guidance for coding agents working in this project"
         },
+        # The same guidance as claude_md, packaged as a Claude Code skill —
+        # for projects that already have a CLAUDE.md lyman shouldn't clobber.
+        # `optional:` keeps `new` from planting it (a fresh scaffold gets
+        # claude_md instead); `alternative:` on claude_md points here when
+        # `add` refuses to overwrite an existing CLAUDE.md.
+        "claude_skill" => {
+          source: "templates/SKILL.md",
+          dest: ".claude/skills/lyman/SKILL.md",
+          role: :owned,
+          optional: true,
+          description: "Claude Code skill variant of the CLAUDE.md guidance — for projects with their own CLAUDE.md"
+        },
         "gemfile" => {
           source: "templates/Gemfile",
           dest: "Gemfile",
           role: :owned,
-          description: "Client dependencies: shifty (and ostruct for ruby >= 4)"
+          description: "Client dependencies: shifty (plus ostruct for ruby >= 4, cli-ui for the harness display)"
         },
         "gitignore" => {
           source: "templates/gitignore",
@@ -90,6 +103,13 @@ module Lyman
         ARTIFACTS.select { |_, spec| spec[:role] == :managed }
       end
 
+      # What `new` plants: everything except opt-in artifacts (those exist
+      # for situations a fresh scaffold can't be in, like a pre-existing
+      # CLAUDE.md — reach them with `lyman add`).
+      def self.default
+        ARTIFACTS.reject { |_, spec| spec[:optional] }
+      end
+
       def self.source_path(spec, source_root: GEM_ROOT)
         File.join(source_root, spec[:source])
       end

data/lib/lyman/cli/version.rb

@@ -2,6 +2,6 @@ module Lyman
   module CLI
     # The gem's own version — distinct from any artifact's `planted_at`.
     # This is what the manifest's top-level `lyman:` key records.
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/lyman/cli.rb

@@ -80,7 +80,8 @@ module Lyman
               entry ? entry["status"] : "not planted"
             end
 
-          line = "#{name} (#{spec[:role]}) #{spec[:dest]}#{" — #{status}" if status} — #{spec[:description]}"
+          role = "#{spec[:role]}#{", opt-in" if spec[:optional]}"
+          line = "#{name} (#{role}) #{spec[:dest]}#{" — #{status}" if status} — #{spec[:description]}"
           say line
         end
       end

data/templates/CLAUDE.md

@@ -7,8 +7,9 @@ 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).
+- `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/chat.rb` — run the interactive chat harness. Defaults to
   Ollama at `http://localhost:11434/v1`; override with `LYMAN_MODEL` and
   `LYMAN_BASE_URL` env vars.

data/templates/Gemfile

@@ -2,3 +2,6 @@ source "https://rubygems.org"
 
 gem "shifty"
 gem "ostruct" # shifty dependency; no longer a default gem as of ruby 4.0
+# Used only by harness/chat.rb's display layer; drop them if you restyle.
+gem "cli-ui"
+gem "reline"

data/templates/SKILL.md

@@ -0,0 +1,62 @@
+---
+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).
+---
+
+# 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
+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
+  Ollama at `http://localhost:11434/v1`; override with `LYMAN_MODEL` and
+  `LYMAN_BASE_URL` env vars.
+
+## The managed/owned boundary
+
+Everything under the `Lyman::` namespace (`lib/lyman.rb`, `lib/lyman/`) is
+**managed** by the lyman CLI: it was planted here, and `lyman update` can
+refresh it from newer lyman releases. Treat it as a library to extend, not a
+file to hand-edit — if you need to change one, run `lyman eject <name>` first,
+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/`.
+
+## Four load-bearing facts
+
+1. **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
+   `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
+   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
+   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.
+
+## Other conventions
+
+- `lyman doctor` smoke-tests the pipeline end to end against a stub
+  transport — run it after `lyman update` or whenever something feels off.
+- `lyman list` shows what's managed, owned, or ejected in this project.
+- Messages use string keys throughout, matching the OpenAI-compatible wire
+  format — no symbol-key message hashes.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lyman
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Joel Helbling
@@ -83,6 +83,7 @@ files:
 - lib/lyman/workers/tool_execution.rb
 - templates/CLAUDE.md
 - templates/Gemfile
+- templates/SKILL.md
 - templates/gitignore
 - templates/lib_lyman.rb
 homepage: https://github.com/joelhelbling/lyman
@@ -104,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.15
 specification_version: 4
 summary: A composable agentic harness, delivered as code you own — a pure generator
   in the shadcn/ui mold, built on shifty