mistri 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de242bfa63b5f170166c93613fc2a2807971d45b792a6200eb60805c4f41c977
-  data.tar.gz: 362d523bba1848e2b552ece5906b1554c4a54820379c9f8e7a3e93430144a9c1
+  metadata.gz: d46cab51a8a899ddd2e3cd0284a7e9eb4185d1362af158303adb97c2a404a657
+  data.tar.gz: 548bf1b8cdc9d22f304674eb5b876b624c16f6b3cc31839daba83909f78641a5
 SHA512:
-  metadata.gz: 2ac330d28d201397f03912c893a538e824c5889a999f7afff3dde4cca8fe8e3a1263f4b886623f6c65fa6b732eae02962e72d4d9c6e945215f2aa724af1d82cb
-  data.tar.gz: fa27dd203af02953b311a479992e82f87e526c8b825b6be057ec0c4bffc0a76172b19af11e57ed7c522a15d0f8e063724b74dd5c5173f11118e96736457c4453
+  metadata.gz: 69b2758b3b137714bb2bffc170ff6520f1d38851230ba19acabbb50042d28234ce934d74555fd328d12d1e8002afe6d96bab8dd21a06567411252e4aeabac973
+  data.tar.gz: 972354e7a95bebfa4f5918efa84f13cbc6e45e9e8dabdf49a60a4d210ecf7c11425866b2ad4d8b648916477568aa2ac69915c98d241311e3778c38667d570558

data/CHANGELOG.md

@@ -3,7 +3,155 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.5.0] - 2026-07-08
+
+- The children registry: Session#children lists every sub-agent a session
+  has spawned as a Mistri::Child, a window onto the child's own session
+  with name, status, report, transcript(tail:) with image bytes stripped,
+  and say(text) to steer it. All of it derives from the store, so it reads
+  the same from any process, while the child runs and forever after.
+- Completion is a contract: every child ends by writing a terminal entry
+  (done with its report, stopped, or failed with the error), including
+  when the child's run raises, so a crashed child never reads as running.
+
+- Spawn policy is an object: Mistri::Spawner carries the pool, types,
+  models, headcount, and dispatcher; SubAgent.spawner and SubAgent.pack
+  stay the front doors.
+- Typed workers: the spawner takes types:, a host registry of Definitions
+  by name. A typed child takes its system prompt, tools, and model from
+  the definition; instructions appends; explicit tool and model args
+  override within the pool and allowlist. "general-purpose" stays the
+  built-in composable default. Types fail at construction, never
+  mid-spawn: a definition with unfilled placeholders or tools the pool
+  lacks is a boot-time ConfigurationError.
+- max_children (default 4) caps live workers per session; a spawn past
+  the cap answers in band and freed slots reopen.
+- SubAgent.pack returns the spawn tool plus the management console in one
+  call, the whole kit for a worker-running agent.
+
+- Background mode: spawn_agent takes mode: "background" when the spawner
+  has a dispatcher, returning a truthful receipt immediately (what the
+  child's status says after dispatch, not what the mode promised) while
+  the parent keeps working; the report arrives on its own (above). The
+  dispatcher is a seam: Dispatchers::Inline (default degrade, synchronous
+  but honest) and Dispatchers::Thread ship in the gem, and a queue host
+  plugs one lambda whose job reconstructs tools from the serializable
+  spec and calls SubAgent.run_dispatched.
+- Lifecycle is entries: subagent_dispatched and subagent_started join the
+  terminal, so status walks the store alone: queued, running, interrupted,
+  done, stopped, failed. A job that dies before starting reads :queued,
+  honestly.
+- A background child runs on its own signal: the parent's turn is over, so
+  only stop_agent and the stop flag end it early. workspace: "parent"
+  requires inline mode, enforced in band.
+
+- Report delivery: a background child's terminal outcome reports back to
+  its parent, exactly once. The report queues in the parent's inbox as a
+  typed subagent_report entry and folds at the next turn boundary the way
+  a steer does (the model sees `[Magpie finished] <report>`; failures
+  carry the error, stops say so), and a report landing as a run finishes
+  cleanly extends it one turn so the parent reacts. A :subagent_report
+  event (agent, session_id, status, content) closes the child's lane in
+  whatever UI watched the spawn. Session#pending_inbox is the
+  steers-and-reports view (hosts that wake idle sessions on steers should
+  watch it instead); Session#deliver_report is the idempotent primitive
+  underneath.
+- Dispatched runs are fenced by the child's lease, taken before the
+  run-or-not decision: a queue that redelivers a live job leaves the
+  owner alone, a retry of a finished or cancelled child is a clean no-op,
+  and a retry of a child a crashed process left mid-run runs it again
+  (previously the guard refused it, wedging the child as interrupted
+  forever). Child#finished? and Child#error are new readers.
+
+- The management console: Mistri::Console.tools returns list_agents,
+  read_agent (tail: to choose how much transcript, wait: to block for the
+  report with an in-band timeout), steer_agent, and stop_agent. Every tool
+  is a thin wrapper over Session#children and the Child facade, the same
+  functions a host UI calls, so agent and user control stay structurally
+  equal. Workers answer to name or session id uniformly in every tool;
+  duplicate names resolve to the latest spawn, ids stay unambiguous, and
+  every state answers honestly in band (already done, nothing to steer,
+  stopping needs a lock adapter).
+
+- Stop one child, keep the run: every sub-agent now runs on its own signal
+  derived from the parent's (AbortSignal#derive), so the parent's abort
+  still cascades down while Child#stop ends a single worker and the parent
+  reasons on with "[the X sub-agent was stopped]". Cross-process stops ride
+  the lock adapter's flags; the lease thread turns them into the child's
+  cooperative abort within a tick.
+- A run stopped during its tool phase now reports :aborted. The final
+  assistant message is clean in that case, so the message's stop reason
+  read :completed and a user-stopped run could claim success; the signal
+  is consulted alongside the message.
+
+- The lock adapter: Mistri.locks takes an adapter for cross-process leases
+  and flags (Locks::Memory built in; Locks::RailsCache as an opt-in require,
+  the Stores::ActiveRecord pattern). Locks.hold keeps a lease alive on a
+  heartbeat from a background thread and releases it cleanly, join and all,
+  so a mid-renewal tick can never re-stamp a released lease.
+- Children gain liveness: every child run holds a lease, and with an
+  adapter configured a child that died without writing its terminal entry
+  reads :interrupted instead of :running forever. Without an adapter
+  nothing changes.
+
+- Session#transcript reads the whole conversation back from the store:
+  entries with image bytes stripped, and with include_children every
+  sub-agent's log spliced in after its link entry, tagged with an
+  "origin" key shaped exactly like the live stream's event origins
+  (nesting joined with ">"). A UI that rebuilds from the transcript shows
+  the lanes it showed live, running children's progress-so-far included;
+  hosts stop hand-walking link entries.
+
+- Tool.define takes ends_turn: true for a tool that is the last word of
+  its turn: once it executes, the loop ends the run instead of prompting
+  the model again, so an ask_user tool hands the floor to a human
+  structurally instead of through prompt discipline. The whole batch it
+  arrived in still executes and is answered; a blocked or denied call
+  never executed, so the model keeps the floor; a parked approval outranks
+  it (the run suspends, and an approved ends_turn call ends the resumed
+  run). A pending steer stays queued for the next run. The Result says it
+  happened (Result#handed_off?), so hosts route on the handoff instead of
+  sniffing messages, and task mode returns the handoff as-is rather than
+  re-prompting for JSON while a human holds the floor.
+
+- Store appends tolerate concurrent writers. Sessions have more than one
+  appender by design (the loop, a steer from a web process, a worker's
+  report from a job), so the ActiveRecord store's unique index is now
+  concurrency control rather than a tripwire: a writer that loses the
+  position race retries at the next slot, bounded, then raises loudly.
+  The JSONL store writes each line in a single call, so concurrent
+  appenders interleave whole lines, never fragments.
+
+- The Fake provider streams tool-call arguments in chunks, and each
+  delta's partial carries the in-progress call with arguments parsed so
+  far, the same shape a real assembler builds. A consumer that renders
+  tool input as it arrives (a page preview, a code block) is now testable
+  headless.
+- Each run of a named specialist can carry its own name: the delegate
+  tool takes an optional name argument, so two parallel researchers read
+  as Corgi and Beagle in lanes, lists, and links instead of "researcher"
+  twice. SubAgent.sanitize_label is the one shared sanitizer behind
+  specialist runs and spawner labels.
+
+## [0.4.1] - 2026-07-06
+
+- Terminal events are loop-owned: each attempt's :done or :error is held at
+  a gate and only the accepted attempt's terminal reaches the subscriber. A
+  transient failure that retries and recovers no longer shows the host an
+  error it then walks back, and repeated empty completions no longer emit a
+  :done per attempt.
+- The :retry event carries structure: attempt, max_attempts, and delay ride
+  the event (and its wire form), so a sink can render "Retrying (2/3) in
+  1.3s" without parsing prose. The prose note stays as content. The event
+  no longer carries a stop reason, because a retry is not a stop.
+- RetryPolicy owns attempt classification: error_for(message) returns the
+  provider's error or a synthesized EmptyCompletion for a blank answer.
+  RetryPolicy::EMPTY_COMPLETION replaces the agent-internal constant.
+- The MCP client advertises protocol 2025-11-25, the current spec revision
+  it already negotiated.
+- README: the :retry event and the terminal-events invariant are documented
+  in the reliability section; the MCP section documents eager listing,
+  refresh:, and the duplicate-name raise at Agent.new.
 
 ## [0.4.0] - 2026-07-05
 
@@ -124,7 +272,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   keep their old arity. Events gained an origin field.
 
 - Task mode: Agent#task(input, schema:) runs an exchange that must end in
-  JSON matching the schema — tools run as usual, providers constrain the
+  JSON matching the schema: tools run as usual, providers constrain the
   final answer natively where supported (Anthropic output_config, OpenAI
   text.format strict, Gemini responseJsonSchema when no tools), and the
   answer validates client-side everywhere. A violation goes back to the
@@ -144,8 +292,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Rails integration: `rails generate mistri:install YourModel` creates a
   host-named entry model and its migration for Stores::ActiveRecord
   (MEDIUMTEXT payload on MySQL-family adapters). Streaming sinks under
-  Mistri::Sinks — ActionCable (lazy server, injectable), SSE (outbound
-  frames to any IO), and Coalesced (merges delta bursts to UI speed) — all
+  Mistri::Sinks: ActionCable (lazy server, injectable), SSE (outbound
+  frames to any IO), and Coalesced (merges delta bursts to UI speed), all
   pure Ruby, usable as `agent.run(input, &sink)`. No Railtie: generators
   auto-discover and everything else duck-types.
 

data/README.md

@@ -104,7 +104,7 @@ end
 
 Handlers and hooks can take the run's context as a second argument, and
 `context.app` carries whatever object you pass as `Mistri.agent(context:)`
-— the acting user, a tenant, a request — so tools stay authorization-aware
+(the acting user, a tenant, a request), so tools stay authorization-aware
 without closure gymnastics:
 
 ```ruby
@@ -116,6 +116,21 @@ Mistri::Tool.define("book_hotel", "Books the chosen hotel.") do |args, context|
 end
 ```
 
+A tool can also be the last word of its turn. `ends_turn: true` makes the
+loop end the run once the tool executes, instead of prompting the model
+again: an `ask_user` tool hands the floor to a human structurally, no
+"remember to stop after asking" prompt required. The result says it
+happened (`result.handed_off?`), and the answer arrives as the next run's
+input:
+
+```ruby
+ask_user = Mistri::Tool.define("ask_user", "Ask the human and wait.",
+                               ends_turn: true,
+                               schema: -> { string :question, "The question", required: true }) do |args|
+  "Question presented to the user."
+end
+```
+
 ## Human approval
 
 Mark a tool `needs_approval: true` (or a predicate on its arguments) and the
@@ -152,6 +167,10 @@ finishes cleanly extends the run so it gets answered.
 Mistri::Session.new(store:, id: session_id).steer("Make the headline blue instead.")
 ```
 
+Background workers' reports arrive through the same inbox (see Sub-agents).
+A host that wakes an idle session when a steer lands should watch
+`session.pending_inbox`, which holds both, in arrival order.
+
 ## Sessions
 
 A session is the durable record of a run: an append-only entry log over a
@@ -215,6 +234,10 @@ result = agent.task("Extract the pricing tiers from this page.", schema: schema)
 result.output # => { "tiers" => [...] }, parsed and validated
 ```
 
+A run that suspends for approval, or that an `ends_turn` tool ended,
+returns as-is: validation applies to answers, not handoffs. Route on
+`result.handed_off?` and ask again once the human's answer arrives.
+
 ## Skills
 
 Expert playbooks with progressive disclosure: each skill costs one line in
@@ -248,7 +271,9 @@ agent = Mistri.agent(definition.model,
 Delegate to a child agent with a clean context: exploration fills the
 child's window, and only the final answer returns. Children run on their own
 sessions in your store, linked in the parent transcript; their events stream
-into the parent tagged with an `origin`.
+into the parent tagged with an `origin`. Each run of a specialist can carry
+its own name, so two parallel researchers read as Corgi and Beagle in your
+UI instead of "researcher" twice.
 
 ```ruby
 researcher = Mistri::SubAgent.new(
@@ -260,12 +285,65 @@ agent = Mistri.agent("claude-opus-4-8", tools: [researcher.tool])
 ```
 
 Or hand the model an open spawn tool and let it compose its own workers:
-a name for the event stream, instructions, a tool subset, and a
-host-allowlisted model per child. Several spawns in one turn fan out in
-parallel:
+a name, instructions, a tool subset, and a host-allowlisted model per
+child. Several spawns in one turn fan out in parallel. `pack` is the whole
+kit: the spawn tool plus a management console (`list_agents`, `read_agent`,
+`steer_agent`, `stop_agent`), with curated types and an optional
+dispatcher:
 
 ```ruby
 spawn = Mistri::SubAgent.spawner(provider: provider, tools: [fetch_page, search])
+
+tools = Mistri::SubAgent.pack(
+  provider: provider, tools: [fetch_page, search],
+  types: { "researcher" => Mistri::Definition.load("agents/researcher.md") },
+  models: ["claude-haiku-4-5-20251001"],
+  dispatcher: Mistri::Dispatchers::Thread.new,      # or one lambda onto your queue
+)
+```
+
+A typed worker takes its prompt, tools, and model from the host's
+definition; `general-purpose` stays open for the model to compose.
+`max_children` (default 4) caps live workers, and every policy violation
+answers the model in band.
+
+Everything cross-process (stopping a worker from another process, the
+`:interrupted` liveness read, and the lease fence below) rides a lock
+adapter; configure one at boot. Without it, workers still run, but stops
+need the parent's own signal, a crashed child reads `:running`, and
+dispatched retries are unfenced:
+
+```ruby
+Mistri.locks = Mistri::Locks::RailsCache.new   # Locks::Memory for a single process
+```
+
+With a dispatcher, `spawn_agent` takes `mode: "background"`: the model gets
+a truthful receipt at once and keeps working while the child runs. The
+console manages the roster with the same functions a host UI calls, so
+agent and user control stay structurally equal: either can read a worker's
+transcript, steer it mid-run, or stop it, from any process. When a worker
+finishes, its report delivers itself: a typed entry queues in the parent's
+inbox and folds at the next turn boundary as `[Corgi finished] <report>`
+(failures carry the error), while a `:subagent_report` event settles the
+worker's lane in whatever UI watched the spawn. In a queue host, the job
+rebuilds tools from the serializable spec and calls
+`SubAgent.run_dispatched`, which fences on the child's lease: a redelivered
+job leaves the running owner alone, a retry of a finished child is a no-op,
+and a retry of a crashed one runs it again.
+
+Everything about a child derives from the store and reads the same from
+any process, while it runs and forever after:
+
+```ruby
+session.children               # => [#<Mistri::Child Corgi running>, ...]
+child.status                   # :queued, :running, :done, :stopped, :failed
+child.report                   # the terminal entry's report, once finished
+child.say("Check pricing too") # folds at the child's next turn boundary
+child.stop                     # cooperative, cross-process, within a tick
+
+session.transcript(include_children: true)
+# the whole conversation, each child's log spliced at its link entry and
+# origin-tagged like the live stream: a reloading UI rebuilds its lanes
 ```
 
 ## Editing documents
@@ -304,6 +382,12 @@ tools = Mistri::MCP.tools(client, prefix: "linear",
 agent = Mistri.agent("claude-opus-4-8", tools: tools)
 ```
 
+The bridge lists the server's tools once, at build time; `client.tools(refresh: true)`
+re-lists when a host wants a changed toolset. `prefix:` namespaces local
+names (`linear__create_issue`) because duplicate tool names raise at
+`Agent.new`: collisions fail loud instead of one server's tool silently
+shadowing another's.
+
 Local stdio servers spawn as child processes, credentials in their
 environment. That is also the whole "give the agent a browser" story:
 
@@ -369,6 +453,23 @@ budget = Mistri::Budget.new(turns: 20, cost_usd: 2.00)
 policy = Mistri::RetryPolicy.new(attempts: 3)
 ```
 
+Retries are invisible to the model but not to your UI: each backoff emits a
+`:retry` event carrying `attempt`, `max_attempts`, and `delay`, so a sink can
+show a live "reconnecting" state instead of a silent spinner. Terminal events
+are loop-owned: `:done` and `:error` reach the subscriber only for the
+accepted attempt, so a recovered retry never flashes an error it then walks
+back.
+
+```ruby
+agent.run("Plan the itinerary.") do |event|
+  case event.type
+  when :text_delta then stream(event.delta)
+  when :retry then banner("Retrying (#{event.attempt}/#{event.max_attempts}) in #{event.delay}s")
+  when :done, :error then clear_banner
+  end
+end
+```
+
 ## Images and provider options
 
 ```ruby
@@ -382,8 +483,11 @@ Mistri.agent("claude-opus-4-8", provider_options: { cache: false })
 
 ## Testing
 
-`rake test` is hermetic and fast. `rake integration` runs every feature end
-to end against real provider APIs, once per model in the matrix: an
+`rake test` is hermetic and fast. The Fake provider streams like the real
+ones, tool-call arguments included: each delta's partial carries the
+in-progress call with arguments parsed so far, so a UI that renders tool
+input as it arrives tests headless. `rake integration` runs every feature
+end to end against real provider APIs, once per model in the matrix: an
 Anthropic, an OpenAI, and a Gemini model by default. Scenarios assert that
 coined codenames (a ghost of a word like `Wraithowyn` exists in no training
 data) flowed through tool results, summaries, and child agents: proof of

data/lib/mistri/abort_signal.rb

@@ -32,6 +32,16 @@ module Mistri
       nil
     end
 
+    # A signal that trips when this one does, never the reverse: abort the
+    # derived signal alone and this one runs on. Returns [signal, handle];
+    # remove the handle when the derived work ends, so a finished child
+    # never leaks a callback into a later abort.
+    def derive
+      child = AbortSignal.new
+      handle = on_abort { child.abort!(reason) }
+      [child, handle]
+    end
+
     # Register a callback for the moment of abort. Fires immediately when the
     # signal is already tripped. Returns a handle for #remove_callback.
     def on_abort(&callback)