turnkit 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2859e971c248c783c407f498d81c9dc489f89120dc273edb517b19e56ef42111
-  data.tar.gz: 2afce740b36683dd513a47770353b7fb74ed174297e96ab7e17efece82d446a6
+  metadata.gz: a7069b120432ec902d846961157f5635c946602a8298ed4471f09dde3e3e3e0d
+  data.tar.gz: '09a5d64ff294f89ebde99a6cf1d36dc8731c6cabbf06216d4e9b9551cbe88a1e'
 SHA512:
-  metadata.gz: 3e70a71f00507cad12b7ea9d8f8506d4ae16ddbd7dbfbf3e59808ebdc244392e9dde14cf7ee4ee2d7578351bca0af906bb4ede6a6419e8136cf00706b2115307
-  data.tar.gz: ba707c678fb3dee1211d0e0d2e57eccfe1ac4e15567fb985127602043085693643c70f6f7f5779259f2baf3b437b739d23db3196f500f00ae157a854d6543a44
+  metadata.gz: de794838f5979194aa2469890848eb7cd60932d6f223e95d17be4d8912a6f2777afb55143f9776d7093be2072451c4a7ba0aa83ca8783c82a29375da56a11c90
+  data.tar.gz: c037fb4946a252ebf9bb2e0f99b76cca23d60f29275ce4e07a15f71232d4fdc0dce23337ad1b4b47bacd7df50ca7eedd3cf050c82167bcccb30debaa70cdfe22

data/CHANGELOG.md

@@ -1,12 +1,12 @@
 # Changelog
 
-## 0.2.8 - 2026-06-08
+## 0.2.9 - 2026-06-08
 
-- 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 `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, sub-agents, and persistence.
 
 ## Installation
 
@@ -57,6 +58,13 @@ 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.
+
 ### Models
 
 Set a model:
@@ -92,6 +100,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 +143,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 +163,6 @@ agent = TurnKit::Agent.new(
     },
     required: ["priority", "reason"]
   },
-  prompt_mode: :task
 )
 
 run = agent.run(
@@ -146,8 +173,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,18 +186,22 @@ 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],
@@ -181,7 +214,7 @@ fleet = TurnKit.fleet(
   }
 )
 
-run = fleet.run(
+run = workflow.run(
   "Create a source-grounded brief.",
   input: { topic: "Rails 8 Solid Queue" }
 )
@@ -198,11 +231,36 @@ 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.
+
+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 +273,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
@@ -491,7 +545,7 @@ TurnKit.reconcile_stale!
 | `TurnKit.max_depth` | Limit sub-agent depth. |
 | `TurnKit.max_tool_executions` | Limit tool calls per turn. |
 | `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.on_event` | Subscribe to lifecycle events. |
 
@@ -499,10 +553,14 @@ Set options globally:
 
 ```ruby
 TurnKit.default_model = "gpt-4.1-mini"
+TurnKit.max_spend = 0.25
 TurnKit.max_iterations = 25
 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

data/lib/turnkit/agent.rb

@@ -62,7 +62,7 @@ module TurnKit
       Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
     end
 
-    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, **options)
+    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
       task = task || prompt
       raise ArgumentError, "task is required" if task.to_s.empty?
 
@@ -71,6 +71,7 @@ module TurnKit
       turn = conversation.build_turn(
         trigger_message_id: message.id,
         root_turn_id: root_turn_id || parent_run_root_turn_id(parent_run),
+        prompt_mode: prompt_mode,
         **options
       )
       run = Run.new(turn)

data/lib/turnkit/conversation.rb

@@ -26,17 +26,18 @@ module TurnKit
       async ? turn : turn.run!
     end
 
-    def run!(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, root_turn_id: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET, compact: nil, output_schema: nil, on_event: nil)
-      build_turn(trigger_message_id: trigger_message_id, model: model, budget: budget, parent_turn: parent_turn, parent_tool_execution: parent_tool_execution, root_turn_id: root_turn_id, depth: depth, agent: agent, thinking: thinking, compact: compact, output_schema: output_schema, on_event: on_event).run!
+    def run!(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, root_turn_id: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET, compact: nil, output_schema: nil, prompt_mode: nil, on_event: nil)
+      build_turn(trigger_message_id: trigger_message_id, model: model, budget: budget, parent_turn: parent_turn, parent_tool_execution: parent_tool_execution, root_turn_id: root_turn_id, depth: depth, agent: agent, thinking: thinking, compact: compact, output_schema: output_schema, prompt_mode: prompt_mode, on_event: on_event).run!
     end
 
-    def build_turn(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, root_turn_id: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET, compact: nil, output_schema: nil, on_event: nil)
+    def build_turn(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, root_turn_id: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET, compact: nil, output_schema: nil, prompt_mode: nil, on_event: nil)
       snapshot = latest_message_sequence
       effective_thinking = thinking.equal?(THINKING_UNSET) ? agent.effective_thinking : Agent.normalize_thinking(thinking)
       options = { "trigger_message_id" => trigger_message_id }.compact
       options["thinking"] = effective_thinking
       options["compact"] = compact unless compact.nil?
       options["output_schema"] = output_schema || agent.output_schema if output_schema || agent.output_schema
+      options["prompt_mode"] = prompt_mode.to_sym if prompt_mode
       record = store.create_turn(
         "conversation_id" => id,
         "agent_name" => agent.name,

data/lib/turnkit/turn.rb

@@ -6,7 +6,7 @@ module TurnKit
 
     attr_reader :agent, :conversation, :store, :budget, :depth
     attr_reader :id, :conversation_id, :agent_name, :parent_turn_id, :parent_tool_execution_id
-    attr_reader :root_turn_id, :context_message_sequence, :model, :thinking, :compact, :output_schema
+    attr_reader :root_turn_id, :context_message_sequence, :model, :thinking, :compact, :output_schema, :prompt_mode
     attr_reader :started_at
 
     def initialize(agent:, conversation:, record:, store:, budget: nil, depth: 0, on_event: nil)
@@ -25,6 +25,7 @@ module TurnKit
       @thinking = thinking_from_options
       @compact = compact_from_options
       @output_schema = output_schema_from_options
+      @prompt_mode = prompt_mode_from_options
       @started_at = @record["started_at"]
       @budget = budget || agent.build_budget
       @depth = depth
@@ -112,6 +113,7 @@ module TurnKit
       @thinking = thinking_from_options
       @compact = compact_from_options
       @output_schema = output_schema_from_options
+      @prompt_mode = prompt_mode_from_options
       self
     end
 
@@ -125,7 +127,7 @@ module TurnKit
 
     private
       def model_request
-        prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: agent.effective_prompt_mode(turn: self))
+        prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
         instructions = case agent.system_prompt
         when nil
           prompt.to_s
@@ -191,6 +193,11 @@ module TurnKit
         options["output_schema"] if options.key?("output_schema")
       end
 
+      def prompt_mode_from_options
+        options = (@record["options"] || {}).transform_keys(&:to_s)
+        options["prompt_mode"]&.to_sym if options.key?("prompt_mode")
+      end
+
       def persist_assistant_message(result)
         if result.tool_calls?
           message = conversation.append_message(

data/lib/turnkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurnKit
-  VERSION = "0.2.8"
+  VERSION = "0.2.9"
 end

data/lib/turnkit/{fleet.rb → workflow.rb}

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "agent"
+
 module TurnKit
-  class Fleet
+  class Workflow
     attr_reader :name, :description, :instructions, :tools, :skills, :available_skills
     attr_reader :model, :client, :store, :prompt_mode, :thinking, :compaction, :output_schema
     attr_reader :max_iterations, :timeout, :cost_limit, :max_depth, :max_tool_executions
@@ -21,7 +23,7 @@ module TurnKit
       limits.
     TEXT
 
-    def initialize(name: "orchestrator", description: "", instructions: nil,
+    def initialize(name: "workflow", description: "", instructions: nil,
       tools: [], skills: [], available_skills: [], model: nil, client: nil,
       store: nil, prompt_mode: :task, thinking: nil, compaction: nil,
       output_schema: nil, max_iterations: nil, timeout: nil, max_spend: nil,
@@ -64,9 +66,6 @@ module TurnKit
       )
     end
 
-    alias_method :auto_run, :run
-    alias_method :autorun, :run
-
     def agent(**options)
       build_agent(**options)
     end
@@ -101,5 +100,4 @@ module TurnKit
         Agent.new(**attrs)
       end
   end
-
 end

data/lib/turnkit.rb

@@ -15,7 +15,7 @@ require_relative "turnkit/budget"
 require_relative "turnkit/event"
 require_relative "turnkit/model_request"
 require_relative "turnkit/agent"
-require_relative "turnkit/fleet"
+require_relative "turnkit/workflow"
 require_relative "turnkit/client"
 require_relative "turnkit/conversation"
 require_relative "turnkit/message"
@@ -38,6 +38,7 @@ require_relative "turnkit/tool_runner"
 require_relative "turnkit/turn"
 require_relative "turnkit/usage"
 require_relative "turnkit/run"
+require_relative "turnkit/adapters/codex"
 require_relative "turnkit/adapters/ruby_llm"
 require_relative "turnkit/stores/active_record_store"
 
@@ -96,10 +97,6 @@ module TurnKit
     self.cost_limit = value
   end
 
-  def self.fleet(name = "orchestrator", **options)
-    Fleet.new(name: name, **options)
-  end
-
   def self.reconcile_stale!(before: Clock.now - (timeout || 300))
     store.find_stale_turns(before: before).each do |turn|
       store.update_turn(turn.fetch("id"), "status" => "stale", "completed_at" => Clock.now)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.9
 platform: ruby
 authors:
 - Sam Couch
@@ -24,8 +24,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.14'
-description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, tool
-  calling, skills, sub-agents, context compaction, and persistence.
+description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, application
+  runs, reusable workflows, tool calling, skills, sub-agents, context compaction,
+  and persistence.
 email:
 - sam@samcouch.com
 executables: []
@@ -37,6 +38,7 @@ files:
 - README.md
 - UPGRADE.md
 - lib/turnkit.rb
+- lib/turnkit/adapters/codex.rb
 - lib/turnkit/adapters/ruby_llm.rb
 - lib/turnkit/agent.rb
 - lib/turnkit/budget.rb
@@ -47,7 +49,6 @@ files:
 - lib/turnkit/cost.rb
 - lib/turnkit/error.rb
 - lib/turnkit/event.rb
-- lib/turnkit/fleet.rb
 - lib/turnkit/generators/turnkit/install/templates/conversation.rb
 - lib/turnkit/generators/turnkit/install/templates/create_turnkit_tables.rb
 - lib/turnkit/generators/turnkit/install/templates/initializer.rb
@@ -79,6 +80,7 @@ files:
 - lib/turnkit/turn.rb
 - lib/turnkit/usage.rb
 - lib/turnkit/version.rb
+- lib/turnkit/workflow.rb
 homepage: https://github.com/samuelcouch/turnkit
 licenses:
 - MIT
@@ -106,5 +108,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Ruby/Rails agent runtime for durable AI conversations.
+summary: Ruby/Rails agent runtime for durable AI conversations, runs, and workflows.
 test_files: []