turnkit 0.2.8 → 0.2.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2859e971c248c783c407f498d81c9dc489f89120dc273edb517b19e56ef42111
-  data.tar.gz: 2afce740b36683dd513a47770353b7fb74ed174297e96ab7e17efece82d446a6
+  metadata.gz: 268561a36c656098e1d23ea6de4c17616358ff931e05e1389e707a9e28fe458b
+  data.tar.gz: 8f6731d78fed5b3e3cc94d781c4f4e26accc4f8d05842b5c56eb58a6e7448907
 SHA512:
-  metadata.gz: 3e70a71f00507cad12b7ea9d8f8506d4ae16ddbd7dbfbf3e59808ebdc244392e9dde14cf7ee4ee2d7578351bca0af906bb4ede6a6419e8136cf00706b2115307
-  data.tar.gz: ba707c678fb3dee1211d0e0d2e57eccfe1ac4e15567fb985127602043085693643c70f6f7f5779259f2baf3b437b739d23db3196f500f00ae157a854d6543a44
+  metadata.gz: ae0a246b5937e586c808a25d28f051bafc54c2a922a52d89160eb3f5ef3bf7360b1d637cbb0c170d41eb74cd536638b6f9a1880275bd0ccd2fc8dcb4ac44db5c
+  data.tar.gz: 7ffebcfeadf51f193c7f2277a0842c2f56e00d9ff95d502915924f2a6d7e10744a0a710d1d2f5b1865182a9de21b2cce30edc3e94c16f49626912b93b1fc7063

data/CHANGELOG.md

@@ -1,12 +1,19 @@
 # Changelog
 
-## 0.2.8 - 2026-06-08
+## 0.2.10 - 2026-06-10
 
-- Add autonomous task fleets as reusable single-orchestrator runtimes with workflow skills, tools, guardrails, compaction, and run monitoring.
-- Add `Agent#run` and `TurnKit::Run` for non-interactive application tasks.
-- Improve task-runtime DX with `TurnKit.configure`, `TurnKit.model`, `TurnKit.max_spend`, `TurnKit.fleet`, positional `run("task")`, `run.output`, `run.tool_calls`, and `Tool.terminal!`.
+- Add output audits and file-backed output policies for validating final run output.
+- Add per-tool execution limits and explicit budget errors.
+- Improve workflow event callbacks, model telemetry events, and compaction usage accounting.
+- Add an Amazon memo writer example and batched page reading in the workflow researcher example.
+
+## 0.2.9 - 2026-06-08
+
+- Add `TurnKit::Workflow` for reusable single-orchestrator task runtimes with workflow skills, tools, guardrails, compaction, and run monitoring.
+- Add `Agent#run` and `TurnKit::Run` for non-interactive application tasks, with task prompt behavior by default.
+- Improve task-runtime DX with `TurnKit.configure`, `TurnKit.model`, `TurnKit.max_spend`, `TurnKit::Workflow`, positional `run("task")`, `run.output`, `run.tool_calls`, and `Tool.terminal!`.
 - Support tool instances with constructor-injected dependencies.
-- Add a fleet researcher example and upgrade guide.
+- Add a workflow researcher example and upgrade guide.
 
 ## 0.2.6 - 2026-06-07
 

data/README.md

@@ -4,7 +4,8 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-red.svg)](https://www.ruby-lang.org)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.md)
 
-Build durable Ruby and Rails agents with tools, skills, sub-agents, and persistence.
+Build durable Ruby and Rails agents with conversations, runs, workflows, tools,
+skills, output audits, sub-agents, and persistence.
 
 ## Installation
 
@@ -57,6 +58,18 @@ puts run.output
 
 ## Usage
 
+For runnable, API-key-free examples of the three core entry points, see
+[`examples/core_api`](examples/core_api):
+
+- conversation: durable thread over time;
+- agent run: one bounded application task;
+- workflow: reusable task runner with skills, tools, and limits.
+
+For fuller workflow examples, see:
+
+- [`examples/workflow_researcher`](examples/workflow_researcher): source-grounded research with web tools, batch reads, per-tool limits, and deep monitoring;
+- [`examples/amazon_memo_writer`](examples/amazon_memo_writer): strict memo generation with research tools, a structured terminal submit tool, deterministic format checks, and an LLM output policy.
+
 ### Models
 
 Set a model:
@@ -92,6 +105,23 @@ Use these common providers:
 
 Expect `TurnKit::ModelAccessError` for obvious key mistakes.
 
+To run eligible coding tasks against a ChatGPT Plus/Pro Codex subscription instead of provider API-key billing, use the Codex adapter. It shells out to the official `codex exec` CLI, so authenticate Codex first:
+
+```sh
+codex login --device-auth
+```
+
+Then configure TurnKit:
+
+```ruby
+TurnKit.configure do |config|
+  config.client = TurnKit::Adapters::Codex.new(sandbox: "read-only")
+  config.model = "gpt-5.4"
+end
+```
+
+The Codex adapter does not store ChatGPT tokens or read `~/.codex/auth.json` directly. It reuses Codex CLI auth and records token usage with no TurnKit provider cost, because usage is charged against the user's ChatGPT/Codex plan limits.
+
 ### Conversations
 
 Create a conversation:
@@ -118,10 +148,13 @@ turn = conversation.run!
 puts turn.output_text
 ```
 
-### Application Tasks
+### Runs
+
+Use `Agent#run` when your application needs one non-interactive result. A run is
+the AI equivalent of a service object call: one input, one job, one output.
 
-Use `Agent#run` when your application is executing a task instead of chatting
-with a user:
+Reach for a run when the task is bounded, such as classification, extraction,
+summarization, routing, scoring, or structured JSON generation.
 
 ```ruby
 agent = TurnKit::Agent.new(
@@ -135,7 +168,6 @@ agent = TurnKit::Agent.new(
     },
     required: ["priority", "reason"]
   },
-  prompt_mode: :task
 )
 
 run = agent.run(
@@ -146,8 +178,10 @@ run = agent.run(
 puts run.output_data
 ```
 
-`Agent#run` is a small wrapper over TurnKit's existing conversation and turn
-engine. Existing `conversation.ask` usage is still supported.
+`Agent#run` uses task prompt behavior by default: it treats the input as the
+contract, avoids follow-up questions, and returns the best result it can. It is a
+small wrapper over TurnKit's existing conversation and turn engine. Existing
+`conversation.ask` usage is still supported for multi-turn threads.
 
 Prepare a pending run without calling the model:
 
@@ -157,31 +191,39 @@ request = run.preview
 run.run!
 ```
 
-### Fleets
+### Workflows
 
-Use a fleet when you want to package a reusable autonomous workflow: one
-task-mode orchestrator, workflow skills, tools, defaults, and guardrails. A
-fleet is not a requirement for multi-agent work; it is the reusable runtime for
-getting from input to output.
+Use a workflow when a run graduates into a reusable production capability: a
+named task runner with workflow skills, tools, defaults, guardrails, compaction,
+and output policy.
+
+Workflows fight for their life when the task has a repeatable operating
+procedure: inspect app data, gather context, use sources, draft, verify, save,
+and stop under budget. They are overkill for simple classification or extraction
+runs.
 
 ```ruby
 source_grounded_brief = TurnKit::Skill.from_file("app/ai/skills/source_grounded_brief.md")
 
-fleet = TurnKit.fleet(
-  "brief_writer",
+workflow = TurnKit::Workflow.new(
+  name: "brief_writer",
   instructions: "Create source-grounded briefs and verify claims before final output.",
   skills: [source_grounded_brief],
   tools: [WebSearch.new, ReadWebPage.new, SaveBrief],
   max_spend: 0.25,
   max_iterations: 12,
   max_tool_executions: 25,
+  max_tool_executions_by_name: {
+    web_search: 2,
+    read_web_page: 8
+  },
   compaction: {
     context_limit: 64_000,
     threshold: 0.75
   }
 )
 
-run = fleet.run(
+run = workflow.run(
   "Create a source-grounded brief.",
   input: { topic: "Rails 8 Solid Queue" }
 )
@@ -198,11 +240,40 @@ model-tool loop:
 model → tool → result → model → tool → result → final
 ```
 
-`auto_run` is an alias for `run` when you want the name to emphasize autonomous
-execution:
+For repeated workflows, keep instructions, skills, and tools stable and pass the
+per-run data through `input:`. This gives provider prompt caching the best chance
+to reuse the stable workflow prompt while each run supplies dynamic data.
+
+### Choosing runs, conversations, and workflows
+
+Use the smallest entry point that matches the shape of work:
+
+| Entry point | Use when | Tradeoffs |
+| --- | --- | --- |
+| `Conversation` | A user or app will keep adding messages over time. | Best for durable threads and follow-up steering; history grows, so long threads need compaction. |
+| `Agent#run` | Your app needs one bounded result now. | Best for simple production tasks; repeated complex policies can sprawl across callers. |
+| `TurnKit::Workflow` | A task becomes a named reusable workflow with tools, skills, limits, and observability. | Best cache and packaging story for repeated autonomous work; overkill for one-off/simple tasks. |
+
+Prompt caching and compaction solve different problems:
+
+- prompt caching reduces the cost of repeated stable instructions, tools, and
+  skills;
+- compaction reduces the cost of long dynamic histories;
+- budgets (`max_spend`, `max_iterations`, `max_tool_executions`) keep autonomous
+  loops bounded.
+
+Use `max_tool_executions_by_name` when a workflow needs different budgets for
+different tools. For example, allow many cheap reads but only one final submit
+tool, or cap web searches while allowing a batch page reader.
+
+Reach for separate agents and `sub_agents` only when the isolation is worth the
+extra model calls, such as different models, different tool permissions,
+parallel specialist review, or separate durable child conversations.
+
+Run a workflow with `run`:
 
 ```ruby
-run = fleet.auto_run(
+run = workflow.run(
   "Create compliant outreach for this account.",
   input: lead.attributes,
   max_spend: 0.25,
@@ -215,10 +286,6 @@ run = fleet.auto_run(
 )
 ```
 
-Reach for separate agents and `sub_agents` only when the isolation is worth the
-extra model calls, such as different models, different tool permissions,
-parallel specialist review, or separate durable child conversations.
-
 Use `terminal!` for save or action tools that complete the run:
 
 ```ruby
@@ -235,6 +302,71 @@ class SaveBrief < TurnKit::Tool
 end
 ```
 
+### Output audits and policies
+
+Use output audits for deterministic checks that should not depend on another
+model call: required headings, source counts, forbidden characters, JSON shape,
+or project-specific formatting rules.
+
+```ruby
+no_em_dash = ->(output) do
+  next unless output.include?("—")
+
+  { rule: "no_em_dash", message: "contains an em dash" }
+end
+
+numbered_lists_only = ->(output) do
+  lines = output.lines.each_with_index.filter_map do |line, index|
+    index + 1 if line.match?(/^\s*[-*]\s+/)
+  end
+
+  next if lines.empty?
+
+  {
+    rule: "numbered_lists_only",
+    message: "contains unordered list markers",
+    metadata: { lines: lines }
+  }
+end
+
+workflow = TurnKit::Workflow.new(
+  name: "memo_writer",
+  output_audit: [no_em_dash, numbered_lists_only],
+  output_audit_mode: :fail
+)
+```
+
+Run checks directly when you want to test a renderer or policy without calling a
+model:
+
+```ruby
+audit = TurnKit.audit_output(
+  "1. Recommendation\n- unordered item — fix this\n",
+  constraints: [no_em_dash, numbered_lists_only]
+)
+
+puts audit.clean?
+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`.
+
+```ruby
+workflow = TurnKit::Workflow.new(
+  name: "memo_writer",
+  output_policy: "app/ai/policies/amazon_memo.md",
+  output_policy_model: "gpt-4.1-mini",
+  output_policy_thinking: { effort: :low },
+  output_policy_mode: :report
+)
+```
+
+`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.
+
 ### Prompt Preview
 
 Preview a pending turn:
@@ -272,9 +404,7 @@ class SaveReport < TurnKit::Tool
   parameter :title, :string, required: true
   parameter :body, :string, required: true
 
-  def self.ends_turn? = true
-
-  def self.completion_message(result)
+  terminal! do |result|
     "Saved #{result.fetch("report_id")}."
   end
 
@@ -490,19 +620,28 @@ TurnKit.reconcile_stale!
 | `TurnKit.max_iterations` | Limit model loop iterations. |
 | `TurnKit.max_depth` | Limit sub-agent depth. |
 | `TurnKit.max_tool_executions` | Limit tool calls per turn. |
+| `TurnKit.max_tool_executions_by_name` | Limit specific tools independently. |
 | `TurnKit.timeout` | Limit turn runtime. |
-| `TurnKit.cost_limit` | Limit estimated turn cost. |
+| `TurnKit.max_spend` | Limit estimated turn cost. |
 | `TurnKit.compaction` | Configure context compaction. |
+| `TurnKit.output_policy_model` | Default model for file-backed output policies. |
+| `TurnKit.output_policy_thinking` | Default thinking config for file-backed output policies. |
 | `TurnKit.on_event` | Subscribe to lifecycle events. |
 
 Set options globally:
 
 ```ruby
 TurnKit.default_model = "gpt-4.1-mini"
+TurnKit.max_spend = 0.25
 TurnKit.max_iterations = 25
+TurnKit.max_tool_executions_by_name = { web_search: 2 }
+TurnKit.output_policy_model = "gpt-4.1-mini"
 TurnKit.timeout = 300
 ```
 
+`TurnKit.cost_limit` remains supported as the internal/legacy name for
+`max_spend`.
+
 Set options per agent:
 
 ```ruby

data/UPGRADE.md

@@ -1,13 +1,27 @@
 # Upgrade Guide
 
-This guide covers migrating to the newer task-runtime API. The changes are
-mostly additive: existing `Agent`, `Conversation`, `Tool`, and `Fleet` code
-should continue to work. The recommended migration is about improving developer
-experience and making autonomous workflows easier to read.
+This guide covers migrating to the workflow-based task-runtime API. The
+recommended migration is about making the three work shapes easier to read:
+
+- conversations for durable multi-turn threads;
+- runs for one non-interactive application task;
+- workflows for reusable task runners with tools, skills, limits, and policy.
 
 ## Quick summary
 
-You do **not** need to rewrite existing code immediately.
+Before changing call sites, bump TurnKit to the latest version and run your
+test suite against the new release.
+
+```ruby
+# Gemfile
+gem "turnkit", "~> 0.2.9"
+```
+
+```sh
+bundle update turnkit
+```
+
+Use workflows for reusable autonomous task runners.
 
 Recommended new forms:
 
@@ -17,23 +31,12 @@ TurnKit.configure do |config|
   config.max_spend = 0.25
 end
 
-fleet = TurnKit.fleet("brief_writer", tools: [WebSearch, SaveBrief])
-run = fleet.run("Create a source-grounded brief.", input: { topic: "Rails 8" })
+workflow = TurnKit::Workflow.new(name: "brief_writer", tools: [WebSearch, SaveBrief])
+run = workflow.run("Create a source-grounded brief.", input: { topic: "Rails 8" })
 
 puts run.output
 ```
 
-Old forms still work:
-
-```ruby
-TurnKit.default_model = "gpt-5.2"
-
-fleet = TurnKit::Fleet.new(name: "brief_writer", tools: [WebSearch, SaveBrief])
-run = fleet.run(task: "Create a source-grounded brief.", input: { topic: "Rails 8" })
-
-puts run.output_text
-```
-
 ## Configuration
 
 ### Model name
@@ -112,7 +115,8 @@ puts run.output
 ```
 
 The keyword form still works. The positional string is the recommended form for
-the common case.
+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
 
@@ -130,10 +134,10 @@ The existing keyword form remains valid:
 run = agent.run(task: "Classify later.", async: true)
 ```
 
-## Fleets
+## Workflows
 
-The fleet mental model changed from “many agents” to “one reusable autonomous
-task runtime.” A fleet packages:
+The preferred name for reusable autonomous task runtimes is now workflow. A
+workflow packages:
 
 - one task-mode orchestrator
 - workflow skills
@@ -144,10 +148,8 @@ task runtime.” A fleet packages:
 
 ### Construction
 
-Before:
-
 ```ruby
-fleet = TurnKit::Fleet.new(
+workflow = TurnKit::Workflow.new(
   name: "sales_enrichment",
   tools: [AccountLookup, WebSearch, SaveEnrichment],
   skills: [sales_research_skill],
@@ -155,34 +157,10 @@ fleet = TurnKit::Fleet.new(
 )
 ```
 
-After:
-
-```ruby
-fleet = TurnKit.fleet(
-  "sales_enrichment",
-  tools: [AccountLookup, WebSearch, SaveEnrichment],
-  skills: [sales_research_skill],
-  max_spend: 0.25
-)
-```
-
-`TurnKit::Fleet.new` remains supported.
-
 ### Running
 
-Before:
-
 ```ruby
-run = fleet.run(
-  task: "Enrich this account for responsible outreach.",
-  input: account.attributes
-)
-```
-
-After:
-
-```ruby
-run = fleet.run(
+run = workflow.run(
   "Enrich this account for responsible outreach.",
   input: account.attributes
 )
@@ -190,17 +168,6 @@ run = fleet.run(
 
 `task:` remains supported.
 
-### Auto-run alias
-
-No behavior change.
-
-```ruby
-run = fleet.auto_run("Enrich this account.", input: account.attributes)
-```
-
-Use `auto_run` when the name helps communicate that the fleet should navigate
-from input to output on its own. It is an alias for `run`.
-
 ## Run inspection
 
 New convenience methods were added to `TurnKit::Run`.
@@ -285,10 +252,10 @@ 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 fleets
+## Multi-agent workflows
 
 If you previously modeled every role as a separate agent, consider migrating the
-default path to one fleet with a workflow skill.
+default path to one workflow with a workflow skill.
 
 Before:
 
@@ -315,8 +282,8 @@ workflow = TurnKit::Skill.new(
   TEXT
 )
 
-fleet = TurnKit.fleet(
-  "source_brief",
+source_brief = TurnKit::Workflow.new(
+  name: "source_brief",
   skills: [workflow],
   tools: [WebSearch, ReadWebPage, SaveBrief],
   max_spend: 0.25,
@@ -336,11 +303,11 @@ Keep separate agents when the isolation is worth the extra model calls:
 
 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. Replace `TurnKit::Fleet.new(name: ...)` with `TurnKit.fleet("...")` in new code.
+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 fleets into one fleet plus workflow skills if
+7. Consider collapsing role-agent workflows into one workflow plus workflow skills if
    cost or complexity is a concern.
 
-None of these steps are required for existing code to keep working.
+Run your test suite after migrating call sites.

data/lib/turnkit/adapters/codex.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "tempfile"
+
+module TurnKit
+  module Adapters
+    class Codex < Client
+      Status = Struct.new(:successful, keyword_init: true) do
+        def success? = successful
+      end
+
+      attr_reader :command, :sandbox, :working_directory
+
+      def initialize(command: ENV.fetch("CODEX_COMMAND", "codex"), sandbox: "read-only", working_directory: Dir.pwd, runner: nil)
+        @command = command.to_s
+        @sandbox = sandbox
+        @working_directory = working_directory
+        @runner = runner || method(:run_command)
+      end
+
+      def validate!(model:)
+        raise ModelAccessError, "codex command is required" if command.empty?
+        raise ModelAccessError, "#{command.inspect} was not found. Install OpenAI Codex CLI and run `codex login --device-auth`." unless executable?(command)
+
+        stdout, stderr, status = @runner.call([ command, "login", "status" ], stdin_data: nil, chdir: working_directory)
+        return true if status.success?
+
+        message = [ stderr, stdout ].join("\n").strip
+        hint = "Run `#{command} login --device-auth` to connect your ChatGPT/Codex subscription."
+        raise ModelAccessError, [ "Codex is not authenticated.", message, hint ].reject(&:empty?).join(" ")
+      end
+
+      def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
+        raise ToolError, "TurnKit tools are not supported by the Codex adapter; Codex uses its own local tools" if Array(tools).any?
+
+        with_tempfiles(output_schema: output_schema) do |schema_file, output_file|
+          command = exec_command(model: model, schema_file: schema_file&.path, output_file: output_file.path)
+          stdout, stderr, status = @runner.call(command, stdin_data: prompt_for(messages: messages, instructions: instructions), chdir: working_directory)
+          emit_codex_events(stdout, on_event: on_event)
+          raise ModelAccessError, stderr.strip.empty? ? "codex exec failed" : stderr.strip unless status.success?
+
+          text = read_output(output_file, stdout)
+          Result.new(
+            text: text,
+            output_data: parse_output_data(text, output_schema: output_schema),
+            usage: usage_from_jsonl(stdout),
+            model: model
+          )
+        end
+      end
+
+      private
+        def exec_command(model:, schema_file:, output_file:)
+          args = [ command, "exec", "--json" ]
+          args += [ "--sandbox", sandbox.to_s ] if sandbox
+          args += [ "--model", model.to_s ] unless model.to_s.empty? || model.to_s == "codex"
+          args += [ "--output-schema", schema_file ] if schema_file
+          args += [ "-o", output_file, "-" ]
+          args
+        end
+
+        def prompt_for(messages:, instructions:)
+          parts = []
+          parts << "System instructions:\n#{instructions}" unless instructions.to_s.empty?
+          Array(messages).each do |message|
+            attrs = message.respond_to?(:to_h) ? message.to_h : message
+            attrs = attrs.transform_keys(&:to_s)
+            role = attrs["role"] || "user"
+            content = attrs["content"] || attrs["text"] || ""
+            parts << "#{role}:\n#{content}"
+          end
+          parts.join("\n\n")
+        end
+
+        def with_tempfiles(output_schema:)
+          output_file = Tempfile.new([ "turnkit-codex-output", ".txt" ])
+          schema_file = nil
+          if output_schema
+            schema_file = Tempfile.new([ "turnkit-codex-schema", ".json" ])
+            schema_file.write(JSON.generate(output_schema))
+            schema_file.flush
+          end
+
+          yield schema_file, output_file
+        ensure
+          schema_file&.close!
+          output_file&.close!
+        end
+
+        def read_output(output_file, stdout)
+          output_file.rewind
+          text = output_file.read.to_s
+          return text unless text.empty?
+
+          final_message_from_jsonl(stdout) || stdout.to_s
+        end
+
+        def final_message_from_jsonl(stdout)
+          events = parse_jsonl(stdout)
+          messages = events.filter_map do |event|
+            item = event["item"]
+            next unless item.is_a?(Hash) && item["type"] == "agent_message"
+
+            item["text"]
+          end
+          messages.last
+        end
+
+        def parse_output_data(text, output_schema:)
+          return nil unless output_schema
+
+          JSON.parse(text)
+        rescue JSON::ParserError
+          nil
+        end
+
+        def usage_from_jsonl(stdout)
+          usage = parse_jsonl(stdout).filter_map { |event| event["usage"] if event.is_a?(Hash) }.last || {}
+          input = usage["input_tokens"].to_i
+          cached = usage["cached_input_tokens"].to_i
+          Usage.new(
+            input_tokens: [ input - cached, 0 ].max,
+            output_tokens: usage["output_tokens"].to_i,
+            cached_tokens: cached,
+            thinking_tokens: usage["reasoning_output_tokens"].to_i
+          )
+        end
+
+        def emit_codex_events(stdout, on_event:)
+          return unless on_event
+
+          parse_jsonl(stdout).each do |event|
+            on_event.call(type: "codex.#{event.fetch("type", "event")}", payload: event)
+          end
+        end
+
+        def parse_jsonl(stdout)
+          stdout.to_s.each_line.filter_map do |line|
+            JSON.parse(line)
+          rescue JSON::ParserError
+            nil
+          end
+        end
+
+        def executable?(name)
+          return true if @runner != method(:run_command)
+          return File.executable?(name) if name.include?(File::SEPARATOR)
+
+          ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |path| File.executable?(File.join(path, name)) }
+        end
+
+        def run_command(command, stdin_data:, chdir:)
+          stdout, stderr, status = Open3.capture3(*command, stdin_data: stdin_data, chdir: chdir)
+          [ stdout, stderr, status ]
+        end
+    end
+  end
+end