mistri 0.0.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ef47e99ddd310ccf5ad44af48a9626865b82760040a84cc096d2ed539b06c8a
-  data.tar.gz: 92e0f8c9d928493f59aabc8b39563f63454be7bd870f1d9ebbf3199c044addb9
+  metadata.gz: 53547d685a896819e552e9911249b042715686f47b1c61a3e01ca2a9542f915d
+  data.tar.gz: d902f802d0272fe0ba99525946ee50169c660d43c99d33790061231854cae302
 SHA512:
-  metadata.gz: 1ed7204e694fe68960f0e6e10b875a937f7c1e90abde131b8e06bd1dd489bb9136a86dba7b34a9474044ebf1fe435220520ccad86cf4256ddb884cd2d1f6d6fb
-  data.tar.gz: f6a0b5a222507ad487eb2572e36630cd677ac5b659045f084407ef369401fa8a9cf5eacbebe730b814e6ea98f661e9ade7ec7df8c0f33370e6fce9a5483dec92
+  metadata.gz: c88a9318c689bd4c8dc2b010c8e9e3c939989971d27befcdc60ff45a195cbd414e25564e866d85a2b495d1a2edb515d4892e2060d204382fc93bc430797b2508
+  data.tar.gz: cb8011d2421bdf066a68d0ec3b76c4d6d51ee06a7ebb49479f28d22da92fa04694115f762c3e132a11c17b69c128141b2b652d7cf9148049180cd0cb0ae7aae8

data/CHANGELOG.md

@@ -5,6 +5,219 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-05
+
+- Repository hygiene: coverage floor enforced in CI (simplecov, 90% line),
+  contributing/security/conduct docs, issue and PR templates, Dependabot,
+  and rubygems documentation and bug tracker links.
+
+- Per-tool timeouts: Tool.define(..., timeout: 30) answers in band when a
+  handler stalls, so one hung tool cannot stall the run.
+- :tool_result events carry duration (seconds) for executed tools, feeding
+  latency metrics straight from any sink.
+
+- Mistri::Reminder.every(3, text): a periodic tail reminder for long runs,
+  riding transform_context; due by completed assistant turns, fresh on the
+  wire each time, never persisted.
+
+- Tool hooks: before_tool(call, context) blocks a call by returning the
+  reason as a String, answered to the model in band; it outranks the
+  approval gate and screens approved calls again at settle time, so an
+  aged approval never beats current policy. after_tool(call, result,
+  context) may replace a result (both channels), nil keeps it. Hooks that
+  raise fail safe: before blocks, after answers in band.
+- transform_context accepts an array of transforms, applied in order.
+
+- Result#usage: every run reports its own token and cost accounting,
+  summing persisted turns and compaction calls; task sums across its fix
+  passes. Hosts meter a run without walking the session.
+
+- MCP stdio wire: Client.new(command: [...], env: {...}) spawns a local
+  server as a child process speaking line-delimited JSON-RPC, credentials
+  in its environment per spec. Dying servers and non-protocol stdout fail
+  loudly; close terminates the child.
+
+- MCP connections out of the box: Mistri::MCP::OAuth.start/.complete/
+  .refresh are storage-agnostic services implementing the spec's OAuth 2.1
+  subset (challenge and well-known discovery, RFC 8414 metadata with an
+  OpenID fallback, dynamic client registration as the host application,
+  PKCE with resource indicators, rotating refresh). `rails generate
+  mistri:mcp YourModel` creates a host-named connection model whose rows
+  carry their own flow state and encrypted tokens, with connection.tools
+  bridging straight into an agent and refreshing ahead of expiry.
+
+- MCP bridge: Mistri::MCP::Client speaks Streamable HTTP (initialize
+  handshake, tools/list with pagination, tools/call, sessions with
+  transparent expiry recovery, JSON or SSE responses) with zero new
+  dependencies. Auth is a headers hash or a token string-or-lambda; a
+  lambda re-resolves once on 401, so host refresh logic lives in one place.
+  Mistri::MCP.tools bridges any server (or any duck-typed client, the
+  official mcp gem included) into Mistri tools with allow/deny lists, name
+  prefixing, and per-tool approval gates, so a third-party write tool can
+  ride the human-approval arc.
+
+## [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.
@@ -13,3 +226,5 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## [0.0.1] - 2026-07-04
 
 - Reserved the gem name.
+
+[0.1.0]: https://github.com/mcheemaa/mistri/releases/tag/v0.1.0

data/README.md

@@ -1,5 +1,369 @@
-# 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="https://codecov.io/gh/mcheemaa/mistri"><img alt="Coverage" src="https://codecov.io/gh/mcheemaa/mistri/graph/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.
+
+## MCP
+
+Bridge any Model Context Protocol server's tools into an agent. The client
+speaks Streamable HTTP with zero new dependencies; auth is a token string
+or a lambda that re-resolves once on 401, so refresh logic lives in one
+place. Approval gates compose: a third-party write tool can require a
+human.
+
+```ruby
+client = Mistri::MCP::Client.new(url: "https://mcp.linear.app/mcp",
+                                 token: -> { connection.bearer_token })
+tools = Mistri::MCP.tools(client, prefix: "linear",
+                          gates: { "create_issue" => true })
+
+agent = Mistri.agent("claude-opus-4-8", tools: tools)
+```
+
+Local stdio servers spawn as child processes, credentials in their
+environment. That is also the whole "give the agent a browser" story:
+
+```ruby
+browser = Mistri::MCP::Client.new(
+  command: ["npx", "-y", "@playwright/mcp@latest", "--browser", "chrome", "--headless"],
+)
+agent = Mistri.agent("claude-opus-4-8",
+                     tools: Mistri::MCP.tools(browser, allow: %w[browser_navigate browser_snapshot]))
+```
+
+For the full connect-your-tools story in Rails, generate a connection model
+(name it whatever you like):
+
+```console
+$ bin/rails generate mistri:mcp McpConnection
+```
+
+Each row is one server connection carrying its own OAuth flow state and
+encrypted tokens. The OAuth services underneath (`Mistri::MCP::OAuth.start`,
+`.complete`, `.refresh`) are storage-agnostic, so the same flow works from a
+controller, a GraphQL mutation, or a job. Registration happens as your
+application: `client_name:` is yours to set.
+
+```ruby
+connection, authorize_url = McpConnection.connect(
+  name: "Linear", url: params[:url],
+  client_name: "YourApp", redirect_uri: mcp_callback_url,
+)
+# redirect the user to authorize_url; then, in the callback:
+connection = McpConnection.complete(state: params[:state], code: params[:code])
+
+agent = Mistri.agent("claude-opus-4-8", tools: connection.tools(prefix: "linear"))
+```
+
+## 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