little_ghost 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d24d2ed91efec3898453d20dfea0902edfca7c207fac0983426153208b308a1e
-  data.tar.gz: 74aefcfaf1d9113640f80c6a7c4462c1e4919265705f0eb37c82c9f694eabcae
+  metadata.gz: 271908b0fc40900504fb25cd57d2cbcc8d987ac1ab32a0db58353562793446fc
+  data.tar.gz: 507e5d747e8b341dd60b1edce8811e0dc5b2d41f98cb970e801284b2a326a49f
 SHA512:
-  metadata.gz: de9e90761042a5cad938664be479e6d35d6b0423b213cde3ac05f0a033c4de7468ef96252073b1405a73510c53b650ea5d7c74be2cae9bd68922494a05cfb406
-  data.tar.gz: 96ac0a88302659cad84e80c4491c23ab4bad211b0db8fe9a1bb370dbbcb0a2090d81cc3c922cc62d18ace4804a559efba5bbcb6ee44a6d52cec58ad5f45dfcc0
+  metadata.gz: 830edf81e2d4892e7b72def07ba1d1be85843c8abf5cbb25d744ad520e8586fe9de2ae1cb32084ce832bb1eb866f4fa083af95b93e59df2b3e2c47f4e5c7aea9
+  data.tar.gz: a8dba3d880bdc6adc4271daac984f9ab6384d34520a5be2071e66d1d746f4979952c13e7743364e2de2f2c2aa721057e12e54ca29c83a382b6506e49889ee43e

data/README.md

@@ -148,7 +148,7 @@ upgrading, because interfaces may change between releases.
 - [Core Concepts](docs/guides/core_concepts.md) builds the mental model from Agent to Assembly.
 - [Models and Providers](docs/guides/models_and_providers.md) explains targets, shared roles, and per-request model selection.
 - [Provider Support](docs/guides/providers.md) has copyable setup for hosted APIs and local model servers.
-- [Prompts as Views](docs/guides/prompt_views.md) gives growing instructions, shared pieces, and application values a natural home.
+- [Prompts as Views](docs/guides/prompt_views.md) explains Agent instructions and shared partials, including how to customize LittleGhost's bundled framework prompts.
 - [Tools](docs/guides/tools.md) explains how models call focused Ruby operations.
 - [MCP](docs/guides/mcp.md) connects agents to operations published through the Model Context Protocol.
 - [Structured Results and Content](docs/guides/structured_outputs_and_content.md) covers checked result shapes, images, and documents.

data/docs/guides/assemblies.md

@@ -15,7 +15,7 @@ run = entrypoint.ask(question)
 
 ## Use a Workflow for explicit application logic
 
-A Workflow's `perform` method is ordinary Ruby. Inside it, `invoke` prepares a child call. Read `.output` when you need an intermediate answer. Return the final `invoke` call untouched so its response can stream to the caller.
+A Workflow's `perform` method is ordinary Ruby. Inside it, `invoke` prepares a child call. Read `.output` when you need an intermediate answer. Return the final `invoke` call untouched so its response can stream to the caller, or return a value that Ruby computes from the intermediate answers.
 
 ```ruby
 class ResponseWorkflow < LittleGhost::Workflow
@@ -41,25 +41,37 @@ Every participant passed to `invoke` can be an Agent or another Assembly. By def
 
 Each child Agent keeps its own [prompt view](prompt_views.md). The Workflow supplies request-specific input; it does not replace that Agent's reusable system instructions.
 
-The last child is special because its events become the Workflow's public stream. Return that `invoke` without consuming it:
+The last child is special when its events should become the Workflow's public stream. Return that `invoke` without consuming it:
 
 ```ruby
-# Wrong: this returns a String after consuming the final invocation.
 def perform
-  invoke(CustomerSupportAgent).output
+  invoke CustomerSupportAgent
 end
+```
 
-# Right: this returns the lazy invocation itself.
-def perform
-  invoke CustomerSupportAgent
+When Ruby should compute the caller-visible result, consume every child and return the computed value:
+
+```ruby
+class EvidenceWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    findings = parallel(
+      invoke(LedgerResearchAgent),
+      invoke(PolicyResearchAgent),
+      max_concurrency: 2
+    )
+
+    {"findings" => findings}
+  end
 end
 ```
 
-The first version produces a failed top-level Run whose error is `ProtocolError`. Use `.output` only when Ruby needs an intermediate answer before choosing the next step.
+A returned String becomes the Workflow's textual response. Arrays, mappings, numbers, and booleans become a structured result available through `RunResult#output`, including when the Workflow is exposed with `assembly_as_tool`. Direct structured results must be JSON-compatible and stay within LittleGhost's structured-result size, depth, and complexity limits. Return an explicit value: `nil` remains a `ProtocolError`, which catches forgotten returns.
 
 ### Choose a branch in Ruby
 
-Each branch should end with its final unconsumed invocation:
+Each branch should end with its final unconsumed invocation or a directly computed value:
 
 ```ruby
 class RoutedResponseWorkflow < LittleGhost::Workflow

data/docs/guides/getting_started.md

@@ -197,7 +197,7 @@ app/
 │   └── response_workflow.rb
 ├── prompts/
 │   └── customer_support/
-│       └── system.erb
+│       └── system_prompt.erb
 └── tools/
     └── help_center_lookup_tool.rb
 ```

data/docs/guides/prompt_views.md

@@ -1,8 +1,9 @@
 # Prompts as Views
 
-A short prompt fits nicely inside an Agent class. As the instructions grow, move them into a **prompt view**: an ERB file that LittleGhost finds and renders for the Agent.
-
-This keeps the Agent definition focused. It also gives shared instructions and application values a natural home.
+Keep growing Agent instructions readable by moving them into a **prompt view**:
+an ERB file that LittleGhost finds and renders for the Agent. The Agent prepares
+any application values the prompt needs, while the view holds the instructions
+sent to the model.
 
 ## Start with the inline prompt
 
@@ -28,7 +29,7 @@ class CustomerSupportAgent < LittleGhost::Agent
 end
 ```
 
-Then create `app/prompts/customer_support/system.erb`:
+Then create `app/prompts/customer_support/system_prompt.erb`:
 
 ```erb
 You help customers understand their orders and account.
@@ -38,57 +39,115 @@ Never invent company guidance. Check the help center when policy matters.
 Use the order status tool before making a claim about a private order.
 ```
 
-That is enough. `CustomerSupportAgent` becomes `customer_support`, so LittleGhost looks for `customer_support/system.erb` under `app/prompts`.
+That is enough. LittleGhost turns `CustomerSupportAgent` into the logical path
+`customer_support` and looks for
+`app/prompts/customer_support/system_prompt.erb`.
 
-The prompt is still a system instruction sent to the selected model provider. Keeping it in a view improves organization; it does not keep the content inside your process.
+The prompt is still a system instruction sent to the selected model provider.
+Keeping it in a view improves organization; it does not keep the content inside
+your process.
 
-## Give the view application values
+## Prepare application values with Ruby
 
-Use `prompt_local` for a value the application owns:
+Define `system_prompt` as an instance method when the view needs values from
+your application. Assign those values to instance variables:
 
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
-  prompt_local :company_name, "Northstar"
+  def system_prompt
+    @company_name = "Northstar"
+    @policy_version = SupportPolicy.current_version
+  end
 end
 ```
 
-The local is available by name in the view:
+LittleGhost calls the method before it renders the view. The instance variables
+are available there by the same names:
 
 ```erb
-You are a customer support agent for <%= company_name %>.
+You are a customer support agent for <%= @company_name %>.
+Follow support policy <%= @policy_version %>.
 Answer clearly and concisely.
 ```
 
-A block can resolve a trusted value for each Agent instance. Add it to the Agent class too:
+If you know Rails controllers, the pairing is familiar: the method prepares
+values, and the ERB file presents them. The method's return value is ignored. If
+it raises an exception, the Run fails in the usual way.
+
+An inline `system_prompt` declaration still takes precedence over a view. Remove
+the inline declaration when you want LittleGhost to call the instance method and
+render `system_prompt.erb`.
+
+Subclass actions can call `super` before adding their own values:
 
 ```ruby
-class CustomerSupportAgent < LittleGhost::Agent
-  prompt_local(:policy_version) { SupportPolicy.current_version }
+class BillingSupportAgent < CustomerSupportAgent
+  def system_prompt
+    super
+    @billing_region = "US"
+  end
 end
 ```
 
-Prompt views also receive `invocation`, `run`, and `agent`. Reach for those when the instruction truly depends on the current request. Keep user wording in the caller message unless you deliberately want it inside the system instruction.
+Prompt views also receive three built-in local variables: `invocation` for the
+current request, `run` for its lifecycle, and `agent` for the run-scoped Agent.
+Use them when an instruction genuinely depends on the current request. Keep the
+customer's wording in the caller message unless it belongs in the system
+instruction.
 
-Every rendered value may be sent to the model provider. Pass only data that belongs in the prompt.
+Every rendered value may be sent to the model provider. Put only data that
+belongs in the prompt into the view.
 
 ## Share a small partial
 
 Partials keep repeated instructions in one place. Create `app/prompts/shared/_voice.erb`:
 
 ```erb
-Use a warm, direct voice for <%= company_name %>.
+Use a warm, direct voice for <%= @company_name %>.
 Prefer one clear next step over a long list of possibilities.
 ```
 
 Render it from the Agent's system view:
 
 ```erb
-You are a customer support agent for <%= company_name %>.
+You are a customer support agent for <%= @company_name %>.
+
+<%= partial "shared/voice" %>
+```
+
+The underscore marks a partial. Partials share the Agent's instance variables,
+so `@company_name` remains available without extra wiring.
+
+Use an explicit local for a value that belongs only to one partial. For example,
+create `app/prompts/shared/_closing.erb`:
+
+```erb
+Offer one clear next step for <%= audience %>.
+```
+
+Then pass `audience` when you render it:
 
-<%= partial "shared/voice", locals: {company_name: company_name} %>
+```erb
+<%= partial "shared/closing", locals: {audience: "account owners"} %>
 ```
 
-The underscore marks a partial. Its locals are explicit, so it does not quietly inherit everything available to the parent view.
+Locals do not flow into nested partials unless you pass them again.
+
+## Keep repeated renders predictable
+
+LittleGhost calls `system_prompt` once for each file-backed prompt render. Each
+call starts with the instance variables captured after LittleGhost's
+`after_initialize` callbacks finish. Values left behind by a later callback,
+Tool, or earlier render do not become prompt assigns by accident.
+
+After preparing the view, LittleGhost restores the Agent's live instance
+variables. The objects assigned to the view are still ordinary Ruby objects,
+though, so the view sees the same mutable objects. Treat them as read-only, or
+duplicate a value before assigning it when the template needs an isolated copy.
+
+For state that should change across invocations, read from `run`, a session, or
+an application object in `system_prompt` instead of relying on an earlier
+prompt render.
 
 ## Choose a different template path
 
@@ -104,10 +163,154 @@ LittleGhost chooses one prompt source in this order:
 
 1. An inline `system_prompt`
 2. An explicit `system_template`
-3. The Agent's conventional `system.erb` view
+3. The Agent's conventional `system_prompt.erb` view
 
 Applications can add prompt lookup roots through `Configuration#prompt_paths`.
-Earlier roots win, which lets application code override a shared prompt package.
+Earlier roots win, so an application can override a view from a shared prompt
+package.
+
+## Customize LittleGhost's framework prompts
+
+You can change LittleGhost's own model-facing language without replacing its
+Ruby behavior. Tool descriptions, structured-result repair requests, context
+summaries, code-mode instructions, and other framework messages all come from
+bundled prompt views under the `little_ghost/` namespace.
+
+### Decide when to customize
+
+Models can respond differently to the same instruction, even when the Tool,
+schema, and task stay the same. Wording that works well with one model may lead
+another model to miss a Tool constraint, mishandle a repair request, or recover
+less reliably from a failed call. Adjusting the relevant framework prompt gives
+you a direct way to improve that interaction without forking LittleGhost.
+
+An override can also align framework language with your application's
+terminology and voice. Start with the narrowest template that covers the
+behavior you want to change, and evaluate it with the models your application
+uses. Keep protocol checks, authorization, and execution limits in Ruby;
+prompt wording guides the model but does not enforce those boundaries.
+
+### Find the prompt you want to change
+
+Browse the catalog from your application:
+
+```sh
+$ little_ghost prompts list
+$ little_ghost prompts list structured_output
+$ little_ghost prompts list structured_output/repair
+$ little_ghost prompts show structured_output/repair/request
+```
+
+The bare `list` command shows top-level features with template counts. Pass a
+feature or component path to browse its immediate children, or use `list --all`
+to print every template key. Keys follow `feature/component/purpose`. For
+example, built-in Tool descriptions live under `tools/built_in`, while JSON
+Schema feedback lives under `tools/validation/schema`. Directories named
+`feedback` contain conditions the model can correct. Directories named `errors`
+contain operational failures.
+
+`show` prints the bundled ERB source. Every bundled template starts with a
+structured ERB comment that explains where LittleGhost renders it, its locals,
+and any formatting constraints. These headers use `<%# ... -%>`, so neither the
+comment nor its trailing newline enters the rendered prompt. Each interior line
+also starts with `#` so Ruby-aware editors recognize the whole header as a
+comment. A `#` line outside `<%# ... -%>` and an HTML comment are output text and
+would be sent to the model.
+
+Bundled prompts use plain text and Markdown. When a prompt needs headings or
+structured sections, the default template uses Markdown headings and lists
+rather than XML-like wrapper tags.
+
+### Copy an override into your application
+
+Copy one template into the default application prompt root before editing it:
+
+```sh
+$ little_ghost prompts copy structured_output/repair/request
+```
+
+That creates
+`app/prompts/little_ghost/structured_output/repair/request.erb`. Use `--root` when the
+application configures a different prompt root:
+
+```sh
+$ little_ghost prompts copy structured_output/repair/request --root config/prompts
+```
+
+Use `--agent` when one Agent needs different wording from the rest of the
+application. Pass the Agent's logical path, which is its underscored class name
+without the `Agent` suffix:
+
+```sh
+$ little_ghost prompts copy structured_output/repair/request --agent customer_support
+```
+
+That creates
+`app/prompts/customer_support/little_ghost/structured_output/repair/request.erb`.
+Namespaced classes use a namespaced logical path, such as
+`Admin::CustomerSupportAgent` becoming `admin/customer_support`.
+
+Copy the complete catalog when an application deliberately wants to own every
+piece of framework wording:
+
+```sh
+$ little_ghost prompts copy --all
+```
+
+Copy commands refuse to overwrite any existing destination. With `--all`, the
+command checks every destination before it starts writing. Copied templates
+retain their invisible documentation headers so the override remains
+self-explanatory in the application.
+
+### Choose the override scope
+
+For every framework prompt that applies to an Agent invocation, LittleGhost
+uses the first matching template in this order:
+
+1. An invocation-specific `TrustedPath` root
+2. The Agent-scoped directory inside a configured prompt root
+3. The runtime-wide directory inside a configured prompt root
+4. The template bundled with LittleGhost
+
+Each root keeps the same `little_ghost/<key>.erb` namespace. Agent scope inserts
+the logical path before that namespace.
+
+Runtime-wide overrides normally live in the default `app/prompts` root. Add or
+replace configured roots when the application uses another location:
+
+```ruby
+LittleGhost.configure do |config|
+  config.prompt_paths = ["config/prompts", "app/prompts"]
+end
+```
+
+The uncommon invocation-specific layer is explicit because it can change model
+instructions for only one call. From `config/little_ghost.rb`:
+
+```ruby
+campaign_prompts = LittleGhost::TrustedPath.new(
+  path: File.expand_path("campaign_prompts", __dir__)
+)
+
+CustomerSupportAgent.ask(
+  "Where is my order?",
+  template_paths: [campaign_prompts]
+)
+```
+
+The invocation root contains
+`little_ghost/structured_output/repair/request.erb`, as a runtime root does.
+Direct `LittleGhost.generate` calls accept the same `template_paths:` option.
+
+### Know what an override can change
+
+Framework templates control model-facing language, not protocol roles, Tool
+names, schemas, validation behavior, security checks, or execution limits. A
+required template cannot render as blank.
+
+LittleGhost is pre-1.0. Template keys and their documented locals are maintained
+on a best-effort basis until 1.0, so review release notes and copied overrides
+when upgrading.
 
 ## Treat views as application code
 
@@ -115,13 +318,16 @@ Prompt views run as ERB inside the Ruby process and can call Ruby. Keep prompt
 directories with the rest of your application code rather than letting a
 request choose one.
 
-`TrustedPath` is available for the uncommon case where application code selects
-a request-specific root. It marks that choice explicitly; it does not inspect
-or restrict the directory.
+Use `TrustedPath` only when application code needs to select a request-specific
+root. Do not derive its path from a request parameter, model output, or Tool
+argument. The wrapper confirms that the directory exists and resolves symbolic
+links. It does not inspect who can edit the directory or restrict what its ERB
+can execute.
 
 ## Build request-specific input in a Workflow
 
-A prompt view defines reusable instructions for one Agent. A Workflow may still build request-specific input for that Agent:
+A prompt view defines reusable instructions for one Agent. A Workflow may still
+build request-specific input for that Agent:
 
 ```ruby
 invoke CustomerSupportAgent, input: <<~MESSAGE
@@ -132,7 +338,8 @@ invoke CustomerSupportAgent, input: <<~MESSAGE
 MESSAGE
 ```
 
-The Workflow is composing this request. `CustomerSupportAgent` still receives its own system prompt view when it runs.
+The Workflow is composing this request. `CustomerSupportAgent` still receives
+its own system prompt view when it runs.
 
 Continue with [Tools](tools.md) to give those Agents application capabilities
 while keeping model input, trusted context, and delegated sandbox operations

data/lib/little_ghost/agent/context_management.rb

@@ -35,17 +35,6 @@ module LittleGhost
       DEFAULT_PRESERVE_RECENT_MESSAGES = 10 # :nodoc:
       ESTIMATED_CHARS_PER_TOKEN = 4 # :nodoc:
       OUTPUT_LIMIT_STOP_REASONS = %i[max_tokens limit_output_tokens limit_total_tokens limit_turns].freeze # :nodoc:
-      SUMMARIZATION_PROMPT = <<~PROMPT # :nodoc:
-        You are a conversation summarizer. Provide a concise summary of the conversation history.
-
-        Format requirements:
-        - Create a structured, concise summary in bullet-point format.
-        - Do not respond conversationally, address the user directly, or comment on tool availability.
-        - Preserve key topics, questions, significant tool executions and results, code or technical information, and key insights.
-        - Do not assume tool executions failed unless otherwise stated.
-        - Write the summary in the third person.
-      PROMPT
-
       def self.included(base) # :nodoc:
         base.extend(ClassMethods)
         base.class_attribute :context_management_configuration_value
@@ -193,9 +182,9 @@ module LittleGhost
         started_at = monotonic_time
         summary_request = ModelRequest.new(
           messages: [
-            Message.new(role: :system, content: SUMMARIZATION_PROMPT),
+            Message.new(role: :system, content: render_framework_prompt("context_management/summary/system_instruction")),
             *messages,
-            Message.new(role: :user, content: "Please summarize this conversation.")
+            Message.new(role: :user, content: render_framework_prompt("context_management/summary/request"))
           ],
           tools: [],
           settings: request.settings,

data/lib/little_ghost/agent/delegation.rb

@@ -17,8 +17,10 @@ module LittleGhost
     # Static declarations may be combined with a resolver that returns dynamic
     # Subagents::Definition objects. Managed conversations persist when a session
     # store is configured unless <tt>persist: false</tt> keeps them local to one
-    # invocation. An agent exposed as a tool starts with empty history unless
-    # <tt>preserve_context: true</tt> serializes calls and retains its history.
+    # invocation. A class-declared agent exposed as a tool starts with an empty
+    # history and a fresh run-scoped Agent for every call. Set
+    # <tt>preserve_context: true</tt> to serialize calls through one Agent and
+    # retain its history.
     #
     # Tool overrides must be classes. A delegated agent otherwise receives only
     # its own declared tools; it does not inherit the parent's registry. The
@@ -91,8 +93,9 @@ module LittleGhost
 
         # Exposes +agent_class+ as one ordinary tool.
         #
-        # Pass <tt>preserve_context: true</tt> to retain the delegated agent's
-        # conversational history between calls to that tool instance.
+        # By default, every tool call builds and closes a fresh delegated Agent.
+        # Pass <tt>preserve_context: true</tt> to serialize calls through one
+        # Agent and retain its conversational history between calls.
         def agent_as_tool(agent_class, name: nil, description: nil, model: nil, tools: nil,
           preserve_context: false)
           assembly_as_tool(

data/lib/little_ghost/agent/skills.rb

@@ -40,7 +40,8 @@ module LittleGhost
               paths:,
               resource_root: binding.run&.runtime&.skill_resource_root,
               workspace: binding.workspace,
-              sandbox: binding.sandbox
+              sandbox: binding.sandbox,
+              prompt_renderer: binding.agent.method(:render_framework_prompt)
             )
           )
           return [] if catalog.names.empty?
@@ -70,10 +71,6 @@ module LittleGhost
           end
           self.skills_configuration_value = options.merge(paths: configured_paths)
           tools CatalogTools
-          prompt_local(:skills_prompt) do
-            tool = tools.fetch("skills") if tools.names.include?("skills")
-            tool&.catalog&.discovery_prompt.to_s
-          end
           before_invocation :include_skills_prompt
         end
 
@@ -82,8 +79,13 @@ module LittleGhost
 
       private
 
+      def skills_prompt
+        tool = tools.fetch("skills") if tools.names.include?("skills")
+        tool&.catalog&.discovery_prompt.to_s
+      end
+
       def include_skills_prompt(payload)
-        prompt = prompt_locals[:skills_prompt].to_s
+        prompt = skills_prompt
         return Support::Callbacks.continue if prompt.empty?
 
         messages = payload.fetch(:messages).dup

data/lib/little_ghost/agent/tool_loop.rb

@@ -27,8 +27,6 @@ module LittleGhost
     # changed result resets that sequence, while a terminating repeat prevents
     # the duplicate tool body from running again.
     module ToolLoop
-      WARNING = "Repeated tool call detected. Change the approach or arguments before calling this tool again." # :nodoc:
-      FINAL_WARNING = "Final repeated tool call warning. Calling this tool again with identical arguments and result will stop the run." # :nodoc:
       TRACKED_INVOCATION_LIMIT = 1_000 # :nodoc:
 
       def self.included(base) # :nodoc:
@@ -120,7 +118,7 @@ module LittleGhost
           newly_terminated = false
           if repeat && repeat[:count] >= @tool_loop_terminate_at - 1
             unless state[:termination]
-              state[:termination] = "Stopped after detecting a repeated tool-call loop in #{tool_use.name.inspect}."
+              state[:termination] = render_framework_prompt("tools/loop/notices/termination", tool_name: tool_use.name)
               newly_terminated = true
             end
           end
@@ -165,7 +163,9 @@ module LittleGhost
         return Support::Callbacks.continue unless count == @tool_loop_warning_at || count == @tool_loop_terminate_at - 1
 
         action = (count == @tool_loop_warning_at) ? :warn : :final_warning
-        warning = (action == :warn) ? WARNING : FINAL_WARNING
+        warning = render_framework_prompt(
+          (action == :warn) ? "tools/loop/notices/warning" : "tools/loop/notices/final_warning"
+        )
         Instrumentation.publish(
           :tool_loop,
           operation_id: payload[:operation_id],