mistri 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ff0390f2958c74fb1e8a3f46f5ccf05b98e9f02811666cd624f34c80704efb2
-  data.tar.gz: 9d7572d5ce220f9e7478f23dad4f1701d4dce080cbada222eac21788ae8e7e03
+  metadata.gz: 5b5526cf23888f4a5872797ce5a6ebe245c0ff1a857ba8bc717681930f8dd4b8
+  data.tar.gz: fa3f6dee2638cbd1e9c4b60378c40b4ac5a894d3639afff157be6bb70e5fd00f
 SHA512:
-  metadata.gz: 86058bb5ec8de21a786f58158ff90c63fc06aaee36e6e517da0c9659ce167cb5f417a21a47ed0432713d9c3ce83508619d64ff0925c77368eaae3d2536cb5b44
-  data.tar.gz: '068145c75adf083e1f5679387697cb904b5739b8ab96912b8e8135838010bbfe1c2376d003ff850c49f52e59bfa38ff986bdcaa3001330ab33c77e90780aa511'
+  metadata.gz: 8cb353d464264b7d44b8c335cfa938b72136f5273f674d4517632326929216a1a93db9577fb9c75ce66f46a70fc862726ad4444dad6e0a47ba0c8d74f3356ae5
+  data.tar.gz: e5114ba9c5404ee9698c4878599d9f2a7895e3d9c470e1874b0c377b2ac6b59ef62b541940c5798b5cb769df148f0e5a02d835b78bc75a5655905a2fd4bdfcdb

data/CHANGELOG.md

@@ -0,0 +1,177 @@
+# Changelog
+
+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.1.0] - 2026-07-05
+
+- Live integration harness: `rake integration` runs every feature end to
+  end against real provider APIs, once per model in the matrix
+  (MISTRI_INTEGRATION_MODELS overrides the default trio). Scenarios assert
+  that generated codenames flowed through the machinery, so answers prove
+  information flow rather than model knowledge. The default `rake test`
+  stays hermetic.
+- The spawn tool's child models now come only from a host allowlist
+  (`models:` on SubAgent.spawner); without one no model choice is offered,
+  so a hallucinated model id can never construct a provider. Found by the
+  integration harness on its first run.
+- The skills system-prompt section instructs selection more firmly.
+
+- Sub-agents: delegation with a clean context (#2). Mistri::SubAgent names
+  a curated specialist (own provider/system/tools, optional schema: for
+  validated JSON answers); SubAgent.spawner is the open spawn_agent tool
+  where the model writes the child's instructions, grants a tool subset,
+  and may pick a model. Children run fresh sessions on the caller's store,
+  linked in its transcript and on the tool result's ui channel; their
+  events stream into the parent tagged with origin. Parallel spawn calls
+  fan out on the executor pool. Approval-gated tools are refused inside
+  children; gate the delegation itself instead.
+- Tool handlers now receive an optional second argument, ToolContext
+  (session, signal, emit); procs ignore it invisibly and strict lambdas
+  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
+  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
+  model once (fixes:), then raises SchemaError; Result#output carries the
+  validated value. run(output_schema:) exposes raw constrained runs.
+- Schema.violations (a zero-dependency validator for the supported subset,
+  with model-feedable error messages) and Schema.strict (wire preparation:
+  additionalProperties false everywhere, all-required for OpenAI strict).
+
+- Skills: Mistri::Skill and Skills.load (a directory of SKILL.md folders or
+  flat .md files, flat-frontmatter name/description). Pass skills: to the
+  Agent (array or path): descriptions join the system prompt and a
+  read_skill tool serves full bodies on demand, so a skill library costs
+  one line each until used. Hosts with skills in a database construct
+  Skill objects directly.
+
+- 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
+  pure Ruby, usable as `agent.run(input, &sink)`. No Railtie: generators
+  auto-discover and everything else duck-types.
+
+- Retry policy: transient turn failures (429/5xx/529, timeouts, dropped or
+  truncated streams) retry with jittered backoff, honoring retry-after. On
+  by default (retries: on the Agent; false disables, or pass a tuned
+  RetryPolicy). Failed attempts record as retry entries and emit :retry
+  events but never become messages, so retries stay invisible to the model.
+- Errored messages now carry a machine-readable error field ({type, status,
+  retry_after}) alongside error_message; in-stream provider errors keep
+  their wire classification (Anthropic overloaded, OpenAI rate limits,
+  Gemini status codes) instead of folding into prose.
+
+- Two-channel tool results: a handler may return Mistri::ToolResult with
+  content for the model and ui for the host. The ui payload rides the tool
+  message and its :tool_result event, persists with the session for
+  transcript re-renders, and never reaches a provider.
+
+- Context compaction: sessions compact automatically when the context grows
+  into the reserve headroom (compaction: on the Agent, on by default when the
+  model's window is known; pass false to disable). The provider writes a
+  visible structured summary; a compaction entry redirects replay to summary
+  plus kept tail while the full history stays in the store. Cuts land only on
+  user messages so tool pairs never split, parked approvals stay resumable,
+  and second compactions update the first summary. Agent#compact is the
+  manual button, Agent#context_usage the {tokens, window, fraction} gauge,
+  and :compacting/:compaction the events.
+
+- transform_context: an Agent option that reshapes what the model sees each
+  turn (reminders, redaction, windowing) while the stored transcript stays
+  untouched. The lambda receives the replay messages and returns the messages
+  to send; it must keep tool calls paired with their results.
+
+- Steering: Session#steer queues a user message from any process while a run
+  is live. The loop folds pending steers into the transcript at the next turn
+  boundary, and one that arrives as the model finishes cleanly extends the
+  run so it gets answered instead of dangling. Steers compose with approval
+  suspensions: queue a thought, approve, resume.
+
+- Human-in-the-loop approval: a tool marked needs_approval (true or a
+  predicate on its arguments) suspends the run instead of executing. Runs
+  return a Result immediately; decisions are recorded on the session from any
+  process (approve/deny), and resume settles them and continues. No thread
+  ever waits on a human.
+- Every run now returns a Mistri::Result (completed, awaiting_approval,
+  aborted, budget, or error) that delegates text and stop_reason to its final
+  message.
+- Session entries are normalized to one canonical JSON shape across all
+  stores.
+
+- Budget stops report stop_reason :budget, distinct from a user abort.
+- Tool results that are arrays of data serialize as JSON; empty input and
+  duplicate tool names fail loudly at the boundary.
+
+- `Mistri::Memory` and `Mistri::Tools.memory`: durable knowledge across
+  sessions, read and rewritten whole, living wherever the host points it.
+
+- `Mistri::Workspace`: the document store agents work in, with memory,
+  directory, ActiveRecord, and single-document backends, so editing a
+  database column works exactly like editing a file.
+- `Mistri::Tools.files`: the built-in document tools (read_file, write_file,
+  edit_file, find_in_file, list_files). The edit tool speaks the flat
+  old_string/new_string shape models are trained on, tolerates alias keys,
+  and reports misses with the closest region and its exact difference.
+- `Mistri::Edit.replace`: single-edit replacement with replace_all, newline
+  and BOM preservation, and near-miss diagnostics.
+
+- Truncated streams now fail as retryable errors on every provider instead of
+  reading as user cancellations, and their tool calls pair without executing.
+- Provider error turns carry the HTTP status and response body.
+- Budgets measure every ceiling per run, including wall clock.
+
+- `Mistri::Edit`: pure fuzzy text replacement with a uniqueness guarantee,
+  so an edit never silently changes the wrong region; the string core for a
+  workspace-backed edit tool that works against a database as well as a file.
+
+- `Mistri.agent` and `Mistri.provider`: build an agent or provider from a model
+  id, inferring the provider and reading its key from the environment.
+
+- Aborted and truncated turns now replay without provider errors: unusable
+  thinking degrades to text, empty blocks are dropped, every tool call is
+  paired, and budget-only models skip adaptive thinking.
+
+- The error hierarchy: every Mistri failure rescues as `Mistri::Error`.
+- The message protocol: immutable content blocks (text, thinking, image, tool call),
+  messages with provider identity, usage accounting with cost math, stop reasons.
+- The streaming event union: twelve event types, each carrying an immutable
+  partial-message snapshot.
+- `Mistri::Providers::Fake`: a scriptable provider for hermetic host tests.
+- `Mistri::AbortSignal`: a thread-safe cancel latch with abort callbacks.
+- `Mistri::SSE`: an incremental server-sent-events decoder.
+- `Mistri::Transport`: a persistent per-provider streaming connection with
+  status-mapped errors and hard abort of hung streams.
+- `Mistri::PartialJson`: best-effort parsing of in-flight tool arguments.
+- `Mistri::Models`: a capability catalog with graceful passthrough, so unknown
+  models work the day they ship.
+- `Mistri::Providers::Anthropic`: the Messages API streamed, with adaptive
+  thinking, prompt caching, signature round-trips, and eager tool-input
+  streaming.
+- `Mistri::Providers::OpenAI`: the Responses API streamed and stateless, with
+  encrypted reasoning replay and thinking summaries.
+- `Mistri::Providers::Gemini`: generateContent streamed, with unconstrained
+  thinking by default and verbatim thought-signature replay.
+- `Mistri::Agent`: the streaming tool-calling loop, persisting each turn as it
+  completes so aborts and crashes resume without repair.
+- `Mistri::Tool` and `Mistri::Schema`: define tools with a raw JSON Schema or a
+  Ruby schema block; results may be text, JSON, or content blocks.
+- `Mistri::Session` with pluggable stores (`Memory`, `JSONL`, and an optional
+  `ActiveRecord` adapter for the host's own database).
+- `Mistri::Budget`: opt-in ceilings on turns, tokens, cost, and wall-clock;
+  nothing is enforced unless the host sets it.
+
+## [0.0.3] - 2026-07-04
+
+- Repository moved to github.com/mcheemaa/mistri.
+- Development toolchain: Minitest, RuboCop, CI.
+
+## [0.0.1] - 2026-07-04
+
+- Reserved the gem name.

data/NOTICE

@@ -0,0 +1,9 @@
+Mistri
+Copyright (c) 2026 Muhammad Ahmed Cheema
+
+Mistri's architecture is informed by pi (https://github.com/badlogic/pi-mono),
+the agent harness by Mario Zechner, MIT licensed:
+Copyright (c) 2025 Mario Zechner
+
+Mistri also draws on lessons from truffle-rb, an earlier Ruby port of pi by the
+same author as Mistri.

data/README.md

@@ -1,5 +1,316 @@
-# Mistri
+<h1 align="center">مستری</h1>
 
-**Mistri (مستری)** — the fixer. In Urdu, the mistri is the skilled tradesperson you call when you need something built or repaired: the one who actually gets it done.
+<p align="center"><strong>mistri</strong>, the agent harness for Ruby applications.</p>
 
-Mistri is an agent harness for Ruby applications. First release coming soon.
+<p align="center">
+  <a href="https://rubygems.org/gems/mistri"><img alt="Gem Version" src="https://img.shields.io/gem/v/mistri"></a>
+  <a href="https://github.com/mcheemaa/mistri/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mcheemaa/mistri/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="mistri.gemspec"><img alt="Ruby >= 3.2" src="https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D"></a>
+  <a href="Gemfile"><img alt="Runtime dependencies: zero" src="https://img.shields.io/badge/runtime_deps-0-brightgreen"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+</p>
+
+A mistri (Urdu: مستری) is the fixer: the skilled tradesperson who actually
+gets it done. This one lives inside your app, not in a terminal. It runs the
+model loop, executes tools, streams every event, persists sessions to your
+own database, and pauses for a human when a tool needs approval, all with
+zero runtime gem dependencies.
+
+```ruby
+require "mistri"
+
+weather = Mistri::Tool.define(
+  "get_weather", "Current weather for a city.",
+  schema: -> { string :city, "City name", required: true },
+) do |args|
+  Weather.for(args["city"])
+end
+
+agent = Mistri.agent("claude-opus-4-8", tools: [weather]) # reads ANTHROPIC_API_KEY
+
+agent.run("What should I wear in Lahore today?") do |event|
+  print event.delta if event.type == :text_delta
+end
+```
+
+## Why Mistri
+
+- **Built for applications.** Sessions are durable, append-only records in
+  your own store. Runs stop, resume, steer, and compact from any process.
+- **Fire-and-forget human approval.** A gated tool suspends the run and
+  returns immediately. The approval can arrive two days later from a bare
+  web request; nothing sleeps waiting.
+- **Three providers, frontier-deep.** Anthropic, OpenAI, and Gemini, each
+  streamed natively with thinking, prompt caching, parallel tool calls, and
+  constrained JSON output. One message model across all three.
+- **Zero runtime dependencies.** Plain Ruby all the way down.
+- **Verified against real APIs.** A live integration harness runs every
+  feature end to end on every provider (`rake integration`).
+
+## Install
+
+```ruby
+gem "mistri"
+```
+
+## Sixty-second start
+
+```ruby
+agent = Mistri.agent("claude-opus-4-8")
+result = agent.run("Name three Ruby web frameworks.")
+puts result.text
+```
+
+`Mistri.agent` infers the provider from the model id (`claude-*`, `gpt-*`,
+`gemini-*`) and reads the matching key (`ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, `GEMINI_API_KEY`); pass `api_key:` to set it explicitly.
+Every run returns a `Result`: `completed?`, `awaiting_approval?`,
+`aborted?`, `errored?`, with `text` and (for tasks) `output`.
+
+## Tools
+
+A tool is a name, a description, an argument schema, and a block. The block
+returns a String, a Hash (sent as JSON), or content such as an image. The
+agent calls tools, feeds results back, and loops until the model answers;
+independent calls in a turn run in parallel.
+
+```ruby
+weather = Mistri::Tool.define("get_weather", "Current weather for a city.", schema: lambda {
+  string :city, "City name", required: true
+  string :units, "Temperature units", enum: %w[celsius fahrenheit]
+}) do |args|
+  Weather.for(args["city"], units: args["units"] || "celsius")
+end
+```
+
+A tool can speak on two channels: `content` for the model, `ui` for your
+interface. The `ui` payload rides the `:tool_result` event and persists with
+the session, but never reaches a provider:
+
+```ruby
+Mistri::Tool.define("edit_page", "Applies a page edit.") do |args|
+  page = apply(args)
+  Mistri::ToolResult.new(content: "Saved.", ui: { "html" => page })
+end
+```
+
+## Human approval
+
+Mark a tool `needs_approval: true` (or a predicate on its arguments) and the
+run suspends instead of executing it, instantly, with no thread waiting.
+The decision is a one-line session write from any process, any time later;
+`resume` settles it and carries on.
+
+```ruby
+send_gift = Mistri::Tool.define("send_gift", "Sends a real gift.",
+                                needs_approval: ->(args) { args["amount"].to_i > 100 }) do |args|
+  Gifts.send!(args)
+end
+
+result = agent.run("Send Ana a $200 gift")
+result.awaiting_approval?   # => true; nothing executed
+
+# Days later, in a controller:
+Mistri::Session.new(store:, id: session_id).approve(call_id)   # or .deny(call_id, note: "...")
+
+# Then, in a worker:
+Mistri.agent("claude-opus-4-8", tools: tools, session: reloaded).resume
+```
+
+The harness renders nothing: it emits an `:approval_needed` event and your
+app draws the UI.
+
+## Steering
+
+Queue a message into a running exchange from any process. It folds into the
+conversation at the next turn boundary; one that arrives as the model
+finishes cleanly extends the run so it gets answered.
+
+```ruby
+Mistri::Session.new(store:, id: session_id).steer("Make the headline blue instead.")
+```
+
+## Sessions
+
+A session is the durable record of a run: an append-only entry log over a
+pluggable store (memory, JSONL files, or your database).
+
+```ruby
+store = Mistri::Stores::JSONL.new("tmp/sessions")
+session = Mistri::Session.new(store:)
+
+agent = Mistri.agent("claude-opus-4-8", session:)
+agent.run("Start a haiku about the sea.")
+
+# Later, even in another process: reload by id and continue.
+resumed = Mistri.agent("claude-opus-4-8", session: Mistri::Session.new(store:, id: session.id))
+resumed.run("Now finish it.")
+```
+
+In Rails, generate a model (name it whatever you like) and use the
+ActiveRecord store:
+
+```console
+$ bin/rails generate mistri:install AgentEntry
+```
+
+```ruby
+require "mistri/stores/active_record"
+store = Mistri::Stores::ActiveRecord.new(AgentEntry)
+```
+
+## Compaction
+
+Long sessions survive their context window: when the conversation grows into
+the reserve headroom, the provider writes a visible structured summary and
+replay continues from it. The full history stays in your store for
+transcript views. On by default whenever the model's window is known;
+`compaction: false` disables it.
+
+```ruby
+agent.context_usage   # => { tokens: 141_000, window: 200_000, fraction: 0.705 }
+agent.compact         # the manual button
+```
+
+`:compacting` and `:compaction` events carry the summary, so users see
+exactly what the model still remembers.
+
+## Task mode
+
+A run that must end in JSON matching a schema. Tools run as usual; providers
+constrain the final answer natively where they can, and the answer is
+validated client-side everywhere. A violation goes back to the model once,
+then raises. You get a guaranteed shape or a loud error, never silence.
+
+```ruby
+schema = {
+  type: "object",
+  properties: { "tiers" => { type: "array", items: { type: "string" } } },
+  required: ["tiers"],
+}
+
+result = agent.task("Extract the pricing tiers from this page.", schema: schema)
+result.output # => { "tiers" => [...] }, parsed and validated
+```
+
+## Skills
+
+Expert playbooks with progressive disclosure: each skill costs one line in
+the system prompt until the model decides it is relevant and pulls the full
+body through an auto-provided `read_skill` tool.
+
+```ruby
+agent = Mistri.agent("claude-opus-4-8", skills: "app/skills")   # or an array of Mistri::Skill
+```
+
+A skill is a `SKILL.md` (or flat `.md`) with `name:`/`description:`
+frontmatter, or built from database rows with
+`Mistri::Skill.new(name:, description:, body:)`.
+
+## Sub-agents
+
+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`.
+
+```ruby
+researcher = Mistri::SubAgent.new(
+  name: "researcher", description: "Reads pages and answers factual questions.",
+  provider: Mistri.provider("claude-haiku-4-5-20251001"),   # cheaper model for grunt work
+  system: "Research. Report findings only.", tools: [fetch_page],
+)
+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:
+instructions, a tool subset, and a host-allowlisted model per child.
+Several spawns in one turn fan out in parallel:
+
+```ruby
+spawn = Mistri::SubAgent.spawner(provider: provider, tools: [fetch_page, search])
+```
+
+## Editing documents
+
+The document tools (`read_file`, `edit_file`, `write_file`, `find_in_file`,
+`list_files`) work over a workspace: a directory, memory, ActiveRecord, or
+a single value anywhere, like one database column holding a page:
+
+```ruby
+workspace = Mistri::Workspace::Single.new(
+  read: -> { page.html },
+  write: ->(html) { page.update!(html: html) },
+  path: "hero.html",
+)
+agent = Mistri.agent("claude-opus-4-8", tools: Mistri::Tools.files(workspace))
+```
+
+The edit engine matches exactly, then whitespace-tolerantly; an ambiguous
+match refuses (never silently edits the wrong place), and a near-miss error
+names the closest region so the model's retry is one-shot.
+
+## Streaming into Rails
+
+Sinks bridge the event stream to a transport, and compose as blocks:
+
+```ruby
+cable = Mistri::Sinks::ActionCable.new("agent_#{session.id}")
+sink = Mistri::Sinks::Coalesced.new(cable) # merges token bursts to UI speed
+
+agent.run(input, &sink)
+```
+
+`Mistri::Sinks::SSE.new(response.stream)` does the same for
+`ActionController::Live`. There is no Railtie and nothing to configure;
+the generator and stores duck-type into any app.
+
+## Stopping, budgets, reliability
+
+```ruby
+# Trip the signal from anywhere; the partial turn persists, resume is clean.
+signal = Mistri::AbortSignal.new
+agent.run("Draft a long essay.", signal: signal)
+
+# Ceilings are opt-in and off by default.
+budget = Mistri::Budget.new(turns: 20, cost_usd: 2.00)
+
+# Transient failures (429, 5xx, timeouts) retry with backoff, invisibly to
+# the model. On by default; retries: false disables.
+policy = Mistri::RetryPolicy.new(attempts: 3)
+```
+
+## Images and provider options
+
+```ruby
+photo = Mistri::Content::Image.from_bytes(File.binread("chart.png"), mime_type: "image/png")
+agent.run("What trend does this chart show?", images: [photo])
+
+Mistri.agent("gpt-5.5", provider_options: { reasoning: { effort: "high" } })
+Mistri.agent("claude-opus-4-8", provider_options: { cache: false })
+```
+
+## Verified for real
+
+`rake test` is hermetic and fast. `rake integration` runs every feature end
+to end against real provider APIs, once per model in the matrix. 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 information flow, not model knowledge.
+
+```console
+$ MISTRI_INTEGRATION_MODELS=claude-opus-4-8,gpt-5.5 bundle exec rake integration
+```
+
+## Roadmap
+
+`0.2.0`: an MCP client bridge, so any MCP server's tools plug into an agent.
+
+## Credits
+
+Mistri's architecture is informed by [pi](https://github.com/badlogic/pi-mono)
+by Mario Zechner. See NOTICE.
+
+## License
+
+MIT. See LICENSE.

data/lib/generators/mistri/install/install_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/named_base"
+require "rails/generators/active_record"
+
+module Mistri
+  module Generators
+    # bin/rails generate mistri:install AgentEntry
+    #
+    # Creates the session-entry model, named by the host application, and its
+    # migration, ready for Mistri::Stores::ActiveRecord.
+    class InstallGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :name, type: :string, default: "MistriEntry"
+
+      def create_model
+        template "model.rb.tt", File.join("app/models", class_path, "#{file_name}.rb")
+      end
+
+      def create_migration_file
+        migration_template "migration.rb.tt",
+                           File.join(db_migrate_path, "create_#{table_name}.rb")
+      end
+
+      def show_wiring
+        say <<~NOTE
+
+          Wire the store with your model:
+
+            store = Mistri::Stores::ActiveRecord.new(#{class_name})
+            session = Mistri::Session.new(store: store)
+
+          (require "mistri/stores/active_record" where you build it.)
+
+        NOTE
+      end
+
+      private
+
+      # MySQL TEXT caps at 64KB, which a single large tool result can blow
+      # through; MEDIUMTEXT holds 16MB. Postgres text is unbounded.
+      def payload_size
+        adapter = ::ActiveRecord::Base.connection_db_config.adapter.to_s
+        adapter.match?(/mysql|trilogy/) ? ", size: :medium" : ""
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/generators/mistri/install/templates/migration.rb.tt

@@ -0,0 +1,14 @@
+class Create<%= table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= table_name %> do |t|
+      t.string :session_id, null: false, index: true
+      t.integer :position, null: false
+      t.text :payload<%= payload_size %>, null: false
+      t.timestamps
+    end
+
+    # One session has one writer; a colliding append must raise, never
+    # silently reorder entries.
+    add_index :<%= table_name %>, [:session_id, :position], unique: true
+  end
+end

data/lib/generators/mistri/install/templates/model.rb.tt

@@ -0,0 +1,4 @@
+# Session entries for Mistri agents; read and written through
+# Mistri::Stores::ActiveRecord, one row per entry, append-only.
+class <%= class_name %> < ApplicationRecord
+end

data/lib/mistri/abort_signal.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Mistri
+  # A thread-safe, one-way latch for cancelling a run. The host trips it from
+  # any thread; the loop and tools check it cooperatively at safe points, and
+  # the transport registers an on-abort callback to close an in-flight socket,
+  # so even a stalled read stops immediately instead of waiting out its
+  # read timeout.
+  class AbortSignal
+    def initialize
+      @mutex = Mutex.new
+      @aborted = false
+      @reason = nil
+      @callbacks = []
+    end
+
+    def aborted? = @aborted
+
+    attr_reader :reason
+
+    # Trip the latch and fire every registered callback exactly once.
+    # Subsequent calls are no-ops.
+    def abort!(reason = nil)
+      callbacks = @mutex.synchronize do
+        break [] if @aborted
+
+        @aborted = true
+        @reason = reason
+        @callbacks.dup.tap { @callbacks.clear }
+      end
+      callbacks.each { |callback| safely(callback) }
+      nil
+    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)
+      fire_now = @mutex.synchronize do
+        @callbacks << callback unless @aborted
+        @aborted
+      end
+      safely(callback) if fire_now
+      callback
+    end
+
+    # Deregister a callback, so a completed request does not leak its socket
+    # closer into a later abort.
+    def remove_callback(handle)
+      @mutex.synchronize { @callbacks.delete(handle) }
+      nil
+    end
+
+    private
+
+    # An abort must reach every callback; one raising observer cannot be
+    # allowed to strand the others.
+    def safely(callback)
+      callback.call
+    rescue StandardError
+      nil
+    end
+  end
+end