turnkit 0.2.10 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 268561a36c656098e1d23ea6de4c17616358ff931e05e1389e707a9e28fe458b
-  data.tar.gz: 8f6731d78fed5b3e3cc94d781c4f4e26accc4f8d05842b5c56eb58a6e7448907
+  metadata.gz: 2b34c1c2760df56b69b055246a8afcccaec42c5493cce13ca30303c9c7e1e809
+  data.tar.gz: d3ff91766661eddbd6bb8eefba627ceaf13d8d2b2daa673781819cfe71b41a79
 SHA512:
-  metadata.gz: ae0a246b5937e586c808a25d28f051bafc54c2a922a52d89160eb3f5ef3bf7360b1d637cbb0c170d41eb74cd536638b6f9a1880275bd0ccd2fc8dcb4ac44db5c
-  data.tar.gz: 7ffebcfeadf51f193c7f2277a0842c2f56e00d9ff95d502915924f2a6d7e10744a0a710d1d2f5b1865182a9de21b2cce30edc3e94c16f49626912b93b1fc7063
+  metadata.gz: 02a3e913bcfa72bc5fcbd8e18faaf60def5f62b75981c7e72220e994b7874df2a67fd306dd01cde4f9c3a0d5082aa90271bf210c5c4c5876a5015812077df79f
+  data.tar.gz: 0d6d917eeeef41a3a624a31daccdc60f28e4c121b8959ad0ab3d57301be63427e83f2a349a920fa9707bd9f5e2fa2310721f72a8151fbbb44c26a3ec75466259

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.4.0 - 2026-06-19
+
+- Add first-class image generation with `Turn#paint`, `TurnKit.paint`, and `TurnKit::ImageTool`.
+- Persist generated images as durable image messages with normalized metadata, usage, cost, and event callbacks.
+- Add image output policy support and a `generate-image` CLI smoke example for Gemini 16:9 image generation.
+
+## 0.3.0 - 2026-06-10
+
+- Make the task-runtime API skills-first and intentionally breaking: `max_spend` is the only spend-limit name and output validation is exposed as `output_policy` / `policy_audit`.
+- Store message content as ordered typed parts, with text derived from content and tool calls/results persisted in the transcript instead of metadata.
+- Add `load_skill` for progressively disclosed available skills.
+- Add output-policy revision loops with `output_retries`, including skill/policy rehydration in revision prompts.
+- Add deterministic `input_schema` validation before turns are created.
+- Ensure terminal tools never orphan sibling tool calls; skipped siblings receive cancelled executions and tool-result messages.
+- Add turn claiming, tool-runner heartbeats, persisted budget resume, and sub-agent failure details.
+
 ## 0.2.10 - 2026-06-10
 
 - Add output audits and file-backed output policies for validating final run output.

data/README.md

@@ -331,8 +331,8 @@ end
 
 workflow = TurnKit::Workflow.new(
   name: "memo_writer",
-  output_audit: [no_em_dash, numbered_lists_only],
-  output_audit_mode: :fail
+  output_policy: [no_em_dash, numbered_lists_only],
+  output_policy_mode: :fail
 )
 ```
 
@@ -340,7 +340,7 @@ Run checks directly when you want to test a renderer or policy without calling a
 model:
 
 ```ruby
-audit = TurnKit.audit_output(
+audit = TurnKit.check_output_policy(
   "1. Recommendation\n- unordered item — fix this\n",
   constraints: [no_em_dash, numbered_lists_only]
 )
@@ -350,8 +350,8 @@ puts audit.messages
 ```
 
 Use `output_policy` when a semantic judge is worth the extra model call. The
-policy can be a `.md`, `.markdown`, or `.txt` file path, a `TurnKit::OutputPolicy`,
-or any object that responds to `#call` or `#check`.
+policy can be a `.md`, `.markdown`, or `.txt` file path, a `TurnKit::Skill`, a
+`TurnKit::OutputPolicy`, or any object that responds to `#call` or `#check`.
 
 ```ruby
 workflow = TurnKit::Workflow.new(
@@ -364,8 +364,34 @@ workflow = TurnKit::Workflow.new(
 ```
 
 `output_policy_mode: :report` records violations while allowing the run to
-complete. `:fail` marks the run failed after recording the output and audit.
-Policy model usage and cost are counted on the parent run.
+complete. `:fail` marks the run failed after recording the output and audit;
+`:fail` is the default for contract-driven workflows. Policy model usage and
+cost are counted on the parent run.
+
+Add `output_retries:` to turn policy failures into bounded revision loops instead
+of dead ends:
+
+```ruby
+voice = TurnKit::Skill.from_file("app/ai/skills/memo_voice.md")
+
+workflow = TurnKit::Workflow.new(
+  name: "memo_writer",
+  skills: [voice],
+  output_policy: [voice, no_em_dash],
+  output_retries: 2,
+  input_schema: {
+    "type" => "object",
+    "required" => ["project_id"],
+    "properties" => { "project_id" => { "type" => "string" } }
+  }
+)
+```
+
+`skills:` are always loaded into the prompt. `available_skills:` are listed in
+`<skills_available>` and exposed through the `load_skill` tool, so the model can
+load full instructions on demand. Every advertised tool call receives exactly one
+tool result, including validation errors, budget denials, and calls skipped after
+a terminal tool ends the turn.
 
 ### Prompt Preview
 
@@ -433,6 +459,61 @@ puts turn.output_text
 
 Rely on TurnKit to validate tools and model-provided arguments.
 
+### Images
+
+Generate images inside a durable turn with `turn.paint`. The image call uses the
+configured client adapter, records usage and cost on the turn, persists an image
+message, and emits `image.requested` / `image.completed` events.
+
+```ruby
+image = turn.paint(
+  "Create a 16:9 editorial header image for the article.",
+  model: "gemini-3-pro-image-preview",
+  provider: :gemini,
+  size: "1024x576",
+  metadata: { article_id: article.id }
+)
+
+image.url       # provider-hosted URL when returned
+image.to_blob   # generated bytes for base64 responses, or fetched URL bytes
+image.mime_type # "image/png"
+```
+
+For reusable workflow steps, subclass `TurnKit::ImageTool`:
+
+```ruby
+class GenerateHeaderImage < TurnKit::ImageTool
+  description "Generate an article header image."
+  parameter :title, :string, required: true
+
+  model "gemini-3-pro-image-preview"
+  provider :gemini
+  size "1024x576"
+
+  def prompt(title:)
+    "Create a 16:9 editorial header image for #{title}."
+  end
+end
+```
+
+Rails apps can attach generated images from the event stream without TurnKit
+taking a dependency on Active Storage:
+
+```ruby
+TurnKit.on_event = ->(event) do
+  next unless event.type == "image.completed"
+
+  image = TurnKit::ImageResult.from_h(event.payload.fetch(:image))
+  Article.find(event.payload.dig(:metadata, :article_id)).header_image.attach(
+    io: StringIO.new(image.to_blob),
+    filename: "header.png",
+    content_type: image.mime_type
+  )
+end
+```
+
+Require an image before completion with `TurnKit::OutputPolicy.require_image`.
+
 ### Structured Output
 
 Define a schema:
@@ -639,8 +720,7 @@ TurnKit.output_policy_model = "gpt-4.1-mini"
 TurnKit.timeout = 300
 ```
 
-`TurnKit.cost_limit` remains supported as the internal/legacy name for
-`max_spend`.
+`max_spend` is the only spend-limit name in the public API.
 
 Set options per agent:
 

data/UPGRADE.md

@@ -1,313 +1,51 @@
 # Upgrade Guide
 
-This guide covers migrating to the workflow-based task-runtime API. The
-recommended migration is about making the three work shapes easier to read:
+## 0.3.0 is a clean break
 
-- conversations for durable multi-turn threads;
-- runs for one non-interactive application task;
-- workflows for reusable task runners with tools, skills, limits, and policy.
+TurnKit 0.3.0 intentionally removes the short-lived legacy names from the 0.2
+series. The gem is pre-1.0 and the durable transcript schema changed, so migrate
+by updating call sites and reinstalling the generated tables for new projects.
 
-## Quick summary
+### Renames
 
-Before changing call sites, bump TurnKit to the latest version and run your
-test suite against the new release.
+- `TurnKit.cost_limit` → `TurnKit.max_spend`
+- `Agent.new(cost_limit:)` → `Agent.new(max_spend:)`
+- `Workflow.new(cost_limit:)` / `workflow.run(cost_limit:)` → `max_spend:`
+- `output_audit:` → `output_policy:`
+- `output_audit_mode:` → `output_policy_mode:`
+- `run.output_audit` → `run.policy_audit`
+- `run.output_audit_clean?` → `run.policy_clean?`
+- `TurnKit.audit_output(...)` → `TurnKit.check_output_policy(...)`
 
-```ruby
-# Gemfile
-gem "turnkit", "~> 0.2.9"
-```
+The audit result class remains `TurnKit::OutputAudit`; only the public option and
+run-accessor names changed.
 
-```sh
-bundle update turnkit
-```
+### Message schema
 
-Use workflows for reusable autonomous task runners.
+`turnkit_messages.text` was removed. Message `content` is now the canonical
+ordered array of parts:
 
-Recommended new forms:
+- `text`
+- `thinking`
+- `tool_call`
+- `tool_result`
+- opaque provider parts
 
-```ruby
-TurnKit.configure do |config|
-  config.model = "gpt-5.2"
-  config.max_spend = 0.25
-end
+`Message#text` is derived from text parts. New Rails installs should regenerate
+the install migration; there is no compatibility shim for older schemas.
 
-workflow = TurnKit::Workflow.new(name: "brief_writer", tools: [WebSearch, SaveBrief])
-run = workflow.run("Create a source-grounded brief.", input: { topic: "Rails 8" })
+### Workflows
 
-puts run.output
-```
+`TurnKit::Workflow` now forwards options directly to `Agent`. Use
+`workflow.options[:name]` or `workflow.agent` for inspection instead of per-option
+workflow attr readers. Workflow `instructions:` compose with the orchestrator
+preamble by default; pass `preamble: false` to opt out.
 
-## Configuration
+### Skills and policy loops
 
-### Model name
-
-Before:
-
-```ruby
-TurnKit.default_model = "gpt-5.2"
-```
-
-After:
-
-```ruby
-TurnKit.model = "gpt-5.2"
-```
-
-`TurnKit.default_model` remains supported. `TurnKit.model` is the shorter public
-alias for app code and initializers.
-
-### Global setup
-
-Before:
-
-```ruby
-TurnKit.default_model = "gpt-5.2"
-TurnKit.cost_limit = 0.25
-TurnKit.max_iterations = 12
-```
-
-After:
-
-```ruby
-TurnKit.configure do |config|
-  config.model = "gpt-5.2"
-  config.max_spend = 0.25
-  config.max_iterations = 12
-end
-```
-
-`TurnKit.configure` simply yields the `TurnKit` module. There is no separate
-configuration object or DSL.
-
-### Spend limit naming
-
-Before:
-
-```ruby
-TurnKit.cost_limit = 0.25
-```
-
-After:
-
-```ruby
-TurnKit.max_spend = 0.25
-```
-
-`cost_limit` remains supported. Prefer `max_spend` in application-facing code
-because it matches how developers think about autonomous runs.
-
-## Running application tasks
-
-### Agent tasks
-
-Before:
-
-```ruby
-run = agent.run(task: "Classify this lead.", input: lead.attributes)
-puts run.output_text
-```
-
-After:
-
-```ruby
-run = agent.run("Classify this lead.", input: lead.attributes)
-puts run.output
-```
-
-The keyword form still works. The positional string is the recommended form for
-the common case. `Agent#run` uses task prompt behavior by default; pass
-`prompt_mode: :full` if you need conversation-style prompt behavior for a run.
-
-### Pending runs
-
-No behavior change.
-
-```ruby
-run = agent.run("Classify later.", async: true)
-request = run.preview
-run.run!
-```
-
-The existing keyword form remains valid:
-
-```ruby
-run = agent.run(task: "Classify later.", async: true)
-```
-
-## Workflows
-
-The preferred name for reusable autonomous task runtimes is now workflow. A
-workflow packages:
-
-- one task-mode orchestrator
-- workflow skills
-- tools
-- guardrails
-- compaction
-- optional persistence/action tools
-
-### Construction
-
-```ruby
-workflow = TurnKit::Workflow.new(
-  name: "sales_enrichment",
-  tools: [AccountLookup, WebSearch, SaveEnrichment],
-  skills: [sales_research_skill],
-  max_spend: 0.25
-)
-```
-
-### Running
-
-```ruby
-run = workflow.run(
-  "Enrich this account for responsible outreach.",
-  input: account.attributes
-)
-```
-
-`task:` remains supported.
-
-## Run inspection
-
-New convenience methods were added to `TurnKit::Run`.
-
-Before:
-
-```ruby
-run.output_text
-run.tool_executions
-run.turn_records.length
-TurnKit.store.load_turn(run.id)["error"]
-```
-
-After:
-
-```ruby
-run.output
-run.tool_calls
-run.steps
-run.error
-```
-
-Old methods remain available. Prefer the shorter methods in application code,
-examples, and docs.
-
-## Save/action tools
-
-Use `terminal!` for tools that complete the run by saving an artifact or taking
-the final action.
-
-Before:
-
-```ruby
-class SaveBrief < TurnKit::Tool
-  def self.ends_turn? = true
-  def self.completion_message(result) = "Saved #{result.fetch("id")}."
-
-  def call(title:, body:, context:)
-    { "id" => Brief.create!(title: title, body: body).id }
-  end
-end
-```
-
-After:
-
-```ruby
-class SaveBrief < TurnKit::Tool
-  terminal! { |result| "Saved #{result.fetch("id")}." }
-
-  def call(title:, body:, context:)
-    { "id" => Brief.create!(title: title, body: body).id }
-  end
-end
-```
-
-The old `ends_turn?` and `completion_message` methods remain supported. Prefer
-`terminal!` for readability.
-
-## Tool instances
-
-If a tool needs constructor arguments, register an instance instead of a class.
-
-Before, this may have failed at runtime:
-
-```ruby
-class WebSearch < TurnKit::Tool
-  def initialize(client:)
-    @client = client
-  end
-end
-
-agent = TurnKit::Agent.new(tools: [WebSearch])
-```
-
-After:
-
-```ruby
-client = SearchClient.new(api_key: ENV.fetch("SEARCH_API_KEY"))
-agent = TurnKit::Agent.new(tools: [WebSearch.new(client: client)])
-```
-
-This is the recommended pattern for API clients, test doubles, and per-tenant
-dependencies.
-
-## Multi-agent workflows
-
-If you previously modeled every role as a separate agent, consider migrating the
-default path to one workflow with a workflow skill.
-
-Before:
-
-```ruby
-researcher = TurnKit::Agent.new(name: "researcher", tools: [WebSearch])
-writer = TurnKit::Agent.new(name: "writer")
-verifier = TurnKit::Agent.new(name: "verifier")
-
-orchestrator = TurnKit::Agent.new(
-  name: "orchestrator",
-  sub_agents: [researcher, writer, verifier]
-)
-```
-
-After:
-
-```ruby
-workflow = TurnKit::Skill.new(
-  key: "source_grounded_brief",
-  name: "Source Grounded Brief",
-  content: <<~TEXT
-    Research first. Build an evidence pack. Draft only from evidence. Verify
-    important claims. Revise unsupported claims before final output.
-  TEXT
-)
-
-source_brief = TurnKit::Workflow.new(
-  name: "source_brief",
-  skills: [workflow],
-  tools: [WebSearch, ReadWebPage, SaveBrief],
-  max_spend: 0.25,
-  max_tool_executions: 20
-)
-```
-
-Keep separate agents when the isolation is worth the extra model calls:
-
-- different models
-- different tool permissions
-- adversarial review
-- parallel specialist research
-- separate durable child conversations
-
-## Suggested migration order
-
-1. Replace `TurnKit.default_model =` with `TurnKit.model =` in app-level config.
-2. Wrap global settings in `TurnKit.configure` if you have more than one.
-3. Use `TurnKit::Workflow.new(name: "...")` for reusable autonomous task runners.
-4. Replace `run(task: "...")` with `run("...")` where it improves readability.
-5. Replace `run.output_text` with `run.output` in application code.
-6. Replace save/action tool overrides with `terminal!` when convenient.
-7. Consider collapsing role-agent workflows into one workflow plus workflow skills if
-   cost or complexity is a concern.
-
-Run your test suite after migrating call sites.
+- `available_skills:` now exposes a real `load_skill` tool.
+- `output_policy:` accepts `TurnKit::Skill` instances.
+- `output_retries:` controls bounded revision loops. The default policy mode is
+  now `:fail`; use `output_policy_mode: :report` if dirty output should complete.
+- `input_schema:` validates application input before any conversation or turn is
+  created.

data/lib/turnkit/adapters/ruby_llm.rb

@@ -41,6 +41,23 @@ module TurnKit
         normalize_response(response, model: model)
       end
 
+      def paint(prompt:, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: nil, on_event: nil)
+        require "ruby_llm"
+
+        configure_from_environment
+        kwargs = paint_kwargs(
+          model: model,
+          provider: provider,
+          assume_model_exists: assume_model_exists || false,
+          size: size || "1024x1024",
+          with: input_images,
+          mask: mask,
+          params: params || {}
+        )
+        image = ::RubyLLM.paint(prompt, **kwargs)
+        normalize_image_response(image, model: model, provider: provider, params: { "size" => size || "1024x1024" }.merge(params || {}), metadata: metadata)
+      end
+
       private
         def configure_from_environment
           config = ::RubyLLM.config
@@ -182,6 +199,7 @@ module TurnKit
           )
           Result.new(
             text: response_text(response),
+            parts: response_parts(response, tool_calls: tool_calls),
             output_data: response_data(response),
             tool_calls: tool_calls,
             usage: usage,
@@ -189,6 +207,34 @@ module TurnKit
           )
         end
 
+        def response_parts(response, tool_calls:)
+          content = response.respond_to?(:content) ? response.content : response
+          parts = case content
+          when Array
+            content.map { |part| normalize_provider_part(part) }
+          when Hash
+            [ { "type" => "text", "text" => content.to_json } ]
+          else
+            text = content.to_s
+            text.empty? ? [] : [ { "type" => "text", "text" => text } ]
+          end.compact
+          parts + Array(tool_calls).map { |call| { "type" => "tool_call", "id" => call.id, "name" => call.name, "arguments" => call.arguments } }
+        end
+
+        def normalize_provider_part(part)
+          attrs = part.respond_to?(:to_h) ? part.to_h.transform_keys(&:to_s) : nil
+          return { "type" => "text", "text" => part.to_s } unless attrs
+
+          case attrs["type"].to_s
+          when "text", "output_text"
+            { "type" => "text", "text" => attrs["text"] || attrs["content"].to_s }
+          when "thinking", "reasoning"
+            { "type" => "thinking", "text" => attrs["text"] || attrs["content"].to_s, "signature" => attrs["signature"], "redacted" => attrs["redacted"] || false }.compact
+          else
+            { "type" => "provider", "kind" => attrs["type"].to_s, "data" => attrs }
+          end
+        end
+
         def response_text(response)
           content = response.respond_to?(:content) ? response.content : response
           content.is_a?(Hash) || content.is_a?(Array) ? content.to_json : content.to_s
@@ -217,6 +263,47 @@ module TurnKit
 
           response.cost&.total
         end
+
+        def paint_kwargs(kwargs)
+          parameters = ::RubyLLM::Image.method(:paint).parameters
+          return kwargs if parameters.any? { |kind, _| kind == :keyrest }
+
+          accepted = parameters.filter_map { |kind, name| name if %i[key keyreq].include?(kind) }
+          unsupported = kwargs.keys.select { |key| !accepted.include?(key) && !blank?(kwargs[key]) }
+          raise ArgumentError, "RubyLLM image generation does not support: #{unsupported.join(", ")}" if unsupported.any?
+
+          kwargs.slice(*accepted)
+        end
+
+        def blank?(value)
+          value.nil? || value == false || (value.respond_to?(:empty?) && value.empty?)
+        end
+
+        def normalize_image_response(image, model:, provider:, params:, metadata:)
+          usage = Usage.new(
+            input_tokens: image_usage_value(image, "input_tokens"),
+            output_tokens: image_usage_value(image, "output_tokens"),
+            cost: response_cost(image)
+          )
+          part = ImageResult.new(
+            url: image.respond_to?(:url) ? image.url : nil,
+            data: image.respond_to?(:data) ? image.data : nil,
+            mime_type: image.respond_to?(:mime_type) ? image.mime_type : nil,
+            revised_prompt: image.respond_to?(:revised_prompt) ? image.revised_prompt : nil,
+            model: image.respond_to?(:model_id) ? image.model_id : model,
+            provider: provider&.to_s,
+            usage: usage,
+            params: params,
+            metadata: metadata || {}
+          ).to_h.merge("type" => "image")
+
+          Result.new(parts: [ part ], usage: usage, model: part["model"], output_data: { "type" => "image", "images" => [ part ] })
+        end
+
+        def image_usage_value(image, key)
+          usage = image.respond_to?(:usage) ? image.usage || {} : {}
+          (usage[key] || usage[key.to_sym]).to_i
+        end
     end
   end
 end