little_ghost 0.4.0 → 0.6.0

data/docs/guides/skills.md

@@ -0,0 +1,141 @@
+# Give Agents Skills
+
+A Skill is a reusable instruction package that an Agent can discover by name
+and load when a task needs it. Skills keep specialized procedures out of the
+Agent's main prompt.
+
+## Write one focused skill
+
+Create `app/skills/refund_guide/SKILL.md`:
+
+```markdown
+---
+name: refund_guide
+description: Determine which refund guidance applies to a customer request.
+allowed-tools:
+  - help_center_lookup
+compatibility: Requires the refunds help-center collection.
+---
+
+# Apply the refund guidance
+
+1. Load the current refund entry with `help_center_lookup`.
+2. Compare the purchase date and item category with the returned guidance.
+3. State which facts support the decision and which facts are still missing.
+4. Return the analysis to the application instead of issuing a refund.
+```
+
+Each immediate child of a configured skill root may contain one `SKILL.md`.
+Front matter requires a single-line `name` and `description`. Names contain
+only letters, numbers, underscores, and hyphens. `allowed-tools` and
+`compatibility` are optional information shown to the model.
+
+A Skill may also include supporting files in `references/`, `scripts/`, or
+`assets/`. Keep the main instructions short and point to a resource only when
+the task needs it.
+
+## Let an Agent discover skills
+
+The conventional root is `app/skills`:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  system_prompt "Use an available skill when a request needs a documented procedure."
+  tools HelpCenterLookupTool
+  skills
+end
+```
+
+At runtime, the Agent receives a short catalog of skill names, descriptions,
+and locations. The generated `skills` Tool loads the full instructions when
+the model selects one. An empty catalog adds nothing to the prompt and no Tool.
+
+You can use another application-owned directory or expose only selected
+skills:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  skills paths: [File.expand_path("../../support_skills", __dir__)],
+    only: %w[refund_guide]
+end
+```
+
+Paths may also come from a callable resolved for each Run. Build the path from
+application configuration, not from a path supplied by the model or request.
+
+## Pair instructions with Tools
+
+`allowed-tools` tells the model which Tools a Skill expects. It doesn't add or
+enable those Tools. The Agent's `tools` declaration remains the source of what
+the model can call, and each Tool applies its normal application checks.
+
+This separation makes Skills safe to use as guidance: changing a Markdown file
+can change what the Agent tries, but it can't grant a new Tool, provider,
+filesystem path, or credential.
+
+> **Safety note:** Keep configured skill directories under application control
+> and review Skill changes as prompt changes. A Skill can contain mistaken or
+> outdated instructions, so application code should continue to check any
+> operation that has side effects.
+
+## Make resources available to code mode
+
+Ordinary Skill loading needs no Workspace configuration. If model-authored code
+also needs to read Skill resources, give those resources a stable model-visible
+location:
+
+```ruby
+require "fileutils"
+require "tmpdir"
+
+skill_root = File.expand_path("../../app/skills", __dir__)
+
+LittleGhost.configure do |config|
+  config.skill_paths = [skill_root]
+  config.skill_resource_root = "workspace://skills"
+
+  config.workspace = lambda do |**|
+    root = Dir.mktmpdir("little-ghost-skills-")
+    LittleGhost::Workspace.new(
+      root:,
+      paths: {skills: skill_root},
+      teardown: lambda do |workspace:, **|
+        FileUtils.remove_entry_secure(workspace.root) if File.exist?(workspace.root)
+      end
+    )
+  end
+
+  config.sandbox = {
+    provider: :native,
+    files: {root: :read_write, skills: :read_only},
+    root_filesystem: :isolated,
+    network: :none
+  }
+end
+```
+
+The named Workspace path maps the configured Skill directory, and the Sandbox
+makes it readable without allowing model-authored code to change it. The model
+can then ask the Filesystem Tool for a path such as
+`workspace://skills/refund_guide/references/example.md` without learning the
+host's directory layout. [Workspaces and Sandboxes](sandboxing.md) explains how
+to adapt the temporary root, backend, and other grants for your application.
+
+## Write instructions that stand on their own
+
+A useful Skill tells the Agent:
+
+- When the procedure applies.
+- Which information it needs before deciding.
+- Which named Tools or resources help.
+- What result the caller expects.
+- Which action remains with the application.
+- What to do when information is missing or conflicts.
+
+Use direct instructions and stable domain language. Avoid repeating the
+Agent's general prompt or relying on Tool behavior that the Tool description
+doesn't promise.
+
+Continue with [Workspaces and Sandboxes](sandboxing.md) when model-authored code
+needs Skill resources. See [Tools](tools.md) for Tool validation, bindings, and
+side effects.

data/docs/guides/structured_outputs_and_content.md

@@ -0,0 +1,135 @@
+# Return Structured Results and Send Rich Content
+
+An Agent can return a checked Ruby value instead of prose. It can also receive
+text alongside images and documents when the selected model supports them.
+
+## Declare a result shape
+
+Use `result_schema` on the Agent:
+
+```ruby
+class SupportTriageAgent < LittleGhost::Agent
+  model :customer_support
+  system_prompt "Classify the request using only the supplied evidence."
+
+  result_schema(
+    name: "support_triage",
+    description: "Routing decision for one support request",
+    type: "object",
+    properties: {
+      category: {
+        type: "string",
+        enum: %w[billing delivery returns other]
+      },
+      urgent: {type: "boolean"},
+      summary: {type: "string", maxLength: 500}
+    },
+    required: %w[category urgent summary],
+    additionalProperties: false
+  )
+end
+
+run = SupportTriageAgent.ask("My package is missing and I leave tomorrow.")
+
+if run.completed?
+  triage = run.result.output
+  route_request(category: triage.fetch("category"), urgent: triage.fetch("urgent"))
+else
+  report_failure(run.error)
+end
+```
+
+Every object in a result schema must set `additionalProperties: false` and list
+every property in `required`. The top-level type must be `object`. LittleGhost
+checks the supported JSON Schema subset when the Agent is defined and checks
+the returned value again before publishing a `LittleGhost::StructuredResult`.
+
+LittleGhost supports a focused subset of [JSON Schema Draft
+2020-12](https://json-schema.org/draft/2020-12/json-schema-core). The
+`LittleGhost::Agent.result_schema` API reference lists the accepted keywords.
+
+For a structured Agent, `run.result.output` returns the checked value. For an
+ordinary Agent, it returns text. Use `run.result.structured_result` when you
+also need the schema name.
+
+## Let LittleGhost choose the strategy
+
+The default `strategy: :auto` uses provider-native structured output when it is
+available and otherwise uses a terminal Tool when the model supports reliable
+Tool calls. You can require one strategy:
+
+```ruby
+result_schema(
+  {
+    type: "object",
+    properties: {answer: {type: "string"}},
+    required: ["answer"],
+    additionalProperties: false
+  },
+  name: "answer",
+  strategy: :provider
+)
+```
+
+Use `:provider` or `:tool` when your application depends on that exact path.
+LittleGhost raises `LittleGhost::ConfigurationError` before execution if the
+selected model cannot provide it.
+
+If the first response is missing or invalid, LittleGhost asks the model to
+repair it once. A second invalid response ends the Run with
+`LittleGhost::StructuredResultError`.
+
+> **Safety note:** A checked shape tells you that fields and types match the
+> schema, not that the model's claims are correct. Apply your normal business
+> checks before the result changes data, spends money, or contacts someone.
+
+## Combine text with an image
+
+Build a user `Message` from typed content blocks:
+
+```ruby
+image = LittleGhost::Content::Image.new(
+  data: File.binread("tmp/damaged-package.png"),
+  media_type: "image/png"
+)
+
+message = LittleGhost::Message.new(
+  role: :user,
+  content: [
+    LittleGhost::Content::Text.new(
+      text: "Describe the visible damage without guessing its cause."
+    ),
+    image
+  ]
+)
+
+run = DamageReviewAgent.ask(message)
+```
+
+For a document, include a display name:
+
+```ruby
+document = LittleGhost::Content::Document.new(
+  data: File.binread("tmp/refund-guide.pdf"),
+  media_type: "application/pdf",
+  name: "refund-guide.pdf"
+)
+```
+
+`Image` and `Document` hold the original bytes. Serialization base64-encodes
+them when they cross a JSON boundary, which increases request size. The
+resolved model checks the content type against its advertised input
+capabilities before making the provider request.
+
+> **Safety note:** When content comes from an upload, check its size and actual
+> file type before creating the block. Send it only to a provider you use for
+> that kind of data, and don't treat text extracted from a file as proof of
+> identity or permission.
+
+Content blocks may also accompany a Tool result. They become visible to the
+model, so apply the same size and disclosure checks as you would for user
+content.
+
+Continue with [Compose Agents](assemblies.md) to route a checked result through
+several participants, or [Tools](tools.md) when the result should call Ruby
+code.

data/docs/guides/tools.md

@@ -0,0 +1,355 @@
+# Give agents tools
+
+Tools turn an agent from a writer into a participant in your application. Each
+Tool offers one named operation with checked input. Your Ruby code decides what
+the operation may do.
+
+Start with a narrow read:
+
+```ruby
+class HelpCenterLookupTool < LittleGhost::Tool
+  description "Look up a help center entry by topic."
+  input_schema(
+    type: "object",
+    properties: {topic: {type: "string", enum: %w[refunds shipping]}},
+    required: ["topic"],
+    additionalProperties: false
+  )
+
+  def call(input)
+    {
+      "refunds" => "Refunds are available within 30 days of purchase.",
+      "shipping" => "Standard shipping takes three to five business days."
+    }.fetch(input.fetch("topic"))
+  end
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  system_prompt "Check the help center before stating company guidance."
+  tools HelpCenterLookupTool
+end
+```
+
+The model sees the Tool's name, description, and input schema. When it chooses
+the Tool, LittleGhost checks the arguments, calls `#call`, and returns the
+result to the model. That loop can happen several times before the Agent writes
+its final answer.
+
+## Declare one Tool or a collection
+
+An Agent's `tools` declaration accepts one or more classes. Pass a Tool class
+directly for one operation:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  tools HelpCenterLookupTool
+end
+```
+
+Pass several classes in one declaration, or use several declarations. They are
+equivalent and inherited declarations are retained:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  tools HelpCenterLookupTool, OrderStatusTool
+  tools EscalateConversationTool
+end
+```
+
+For a related or dynamically discovered collection, pass a provider class that
+implements `self.tools(binding)`. It may return Tool classes, Tool instances,
+nested arrays, or `nil`; LittleGhost flattens the result and binds every Tool to
+the current run:
+
+```ruby
+class AccountTools
+  def self.tools(binding)
+    [
+      AccountStatusTool,
+      (CloseAccountTool if binding.run.invocation.context["may_close_account"])
+    ]
+  end
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  tools HelpCenterLookupTool, AccountTools
+end
+```
+
+Prefer `available_if` on an individual Tool when only that operation is
+conditional. Use a provider when the collection itself owns discovery,
+construction, or shared setup for an application or remote service.
+
+LittleGhost does not enforce class names. A useful application convention is
+to end one model-callable operation with `Tool` and a provider of multiple
+operations with `Tools`—for example, `OrderStatusTool` and `AccountTools`.
+The suffix makes `tools AccountTools` readable without introducing a framework
+base class or hiding ordinary Ruby composition.
+
+## Check permission in Ruby
+
+A schema answers “Is this input shaped correctly?” It does not answer “May this
+caller perform this operation?” Use values established by your application to
+answer that second question.
+For sensitive work, read those values inside the Tool:
+
+```ruby
+class OrderStatusTool < LittleGhost::Tool
+  description "Look up an order for the current customer."
+  input_schema(
+    type: "object",
+    properties: {order_number: {type: "string"}},
+    required: ["order_number"],
+    additionalProperties: false
+  )
+
+  def call(input)
+    Orders.status_for(
+      actor_id: run.invocation.actor_id,
+      account_id: run.invocation.context.fetch("account_id"),
+      order_number: input.fetch("order_number")
+    )
+  end
+end
+```
+
+Here, the model chooses `order_number`. The application supplies `actor_id` and
+`account_id` after authenticating the request. The Tool reads those values
+through its run-scoped binding: the objects LittleGhost attaches to a Tool for
+one execution. They are not part of the model's Tool arguments.
+
+The Run also has `context.state`, mutable working state for this execution. When
+saved conversations are configured, it may contain values from an earlier Run.
+Recheck saved values before using them for a permission decision.
+
+> **Safety note:** Keep identity and account membership in the Run's invocation,
+> not in model-selected arguments. A valid Tool input may still name a record
+> the current caller isn't allowed to use.
+
+## Know where a Tool runs
+
+A local Tool is application code. Its `#call` method runs in the same Ruby
+process as LittleGhost, with the same access as the rest of your application. A
+Sandbox contains only work that the Tool explicitly sends through it.
+
+Some Tools deliberately delegate a smaller operation to the Sandbox:
+
+- `LittleGhost::Tools::Filesystem` reads and changes paths through the bound
+  Sandbox. It exposes mutation Tools only when that Sandbox is writable.
+- `LittleGhost::Tools::Shell` runs one argument vector through the bound
+  Sandbox. It does not interpret shell syntax.
+- An application Tool can send work through its bound `sandbox` when it needs
+  the same file and process restrictions. Its bound `workspace` names paths but
+  does not restrict access to them. Do not pass model-selected paths from
+  `Workspace#resolve` to `File`; use Sandbox file operations, which reject
+  symlinks while opening the path.
+
+This distinction keeps the architecture predictable:
+
+```text
+model ──arguments──> Tool#call ──> application service
+                         │
+                         └──> bound Sandbox ──> file or child process
+```
+
+Provider requests also leave from the application process. Sandbox network
+settings apply to processes launched through that Sandbox, not to model
+providers, callbacks, or arbitrary Ruby inside a Tool.
+
+Read [Workspaces and Sandboxes](sandboxing.md) before exposing filesystem or
+process operations to model influence. It shows which paths and commands a
+child process can access, how networking is restricted, and who cleans up the
+resources.
+
+## Use the run-scoped binding
+
+LittleGhost creates and binds fresh Tool instances for each Agent run. A Run is
+one top-level Agent or Assembly execution. A Tool can reach that `run`, its
+`agent`, the `runtime` that holds shared configuration and services, and the
+current `workspace` and `sandbox` through accessors supplied by
+`Tool::Binding`.
+
+That binding carries application collaborators, not model arguments. Keep request
+identity on `run.invocation`, working state on `context.state`, and the
+model-selected input in the `input` passed to `#call`. Keeping those three
+sources distinct makes permission checks easier to follow.
+
+Registries close Tool instances that implement `#close`. Tool instance state
+therefore belongs to one Agent run unless your Tool deliberately talks to a
+shared application service.
+
+Use `available_if` when the run itself determines whether an operation exists.
+The predicate receives the same binding and runs before the Tool is constructed:
+
+```ruby
+class UpdateSlackMessageTool < LittleGhost::Tool
+  available_if { |binding| binding.run.invocation.interface == "slack" }
+end
+```
+
+This controls discovery, not authorization. The Tool must still validate the
+caller identity and account permissions supplied by the application.
+
+## Make concurrency and retries deliberate
+
+LittleGhost may run independent Tool calls concurrently. Mark a Tool
+`exclusive true` when it reads or changes shared mutable state that must not
+overlap another exclusive Tool in the same run:
+
+```ruby
+class UpdateDraftTool < LittleGhost::Tool
+  exclusive true
+  description "Replace one section of the current account's draft."
+  input_schema(
+    type: "object",
+    properties: {
+      section: {type: "string"},
+      content: {type: "string"}
+    },
+    required: %w[section content],
+    additionalProperties: false
+  )
+
+  def call(input)
+    Drafts.replace_section(
+      account_id: run.invocation.context.fetch("account_id"),
+      section: input.fetch("section"),
+      content: input.fetch("content")
+    )
+  end
+end
+```
+
+When LittleGhost selects the fiber backend, concurrent Tool calls can run as
+fibers on one thread. If a Tool calls a library that blocks that thread, every
+other fiber on it must wait too. Suppose the help center lookup later moves to
+a client whose `lookup` method is documented to behave this way. Change only
+the Tool method:
+
+```ruby
+def call(input)
+  LittleGhost.offload_blocking do
+    HelpCenterClient.lookup(input.fetch("topic"))
+  end
+end
+```
+
+Many Ruby I/O calls already let the scheduler run other fibers. Keep those
+calls unchanged. Use `offload_blocking` only when documentation or measurement
+shows that the exact call pauses other fibers and the work can continue on
+another Ruby thread. Configure the call's own timeout or cancellation when it
+provides one.
+
+If most of a Tool's implementation blocks, configure LittleGhost to use the
+`:thread` backend instead of wrapping each call. `exclusive true` prevents
+overlap with another exclusive Tool; it does not change where the Tool runs.
+[Running in Production](production.md#use-an-existing-fiber-scheduler) explains
+the concurrency settings and when to adjust the shared thread pool.
+
+Retries can repeat a Tool call. Prefer read-only operations, idempotency keys,
+or writes that are safe to apply more than once. Do not rely on the prompt to
+prevent duplicate side effects.
+
+Raise `LittleGhost::ToolError` for an expected failure the model can act on.
+Its message is model-visible, so keep it safe to disclose. LittleGhost hides
+unexpected exception messages from the model while retaining the original
+error for trusted application inspection.
+
+## Return values and artifacts
+
+A Tool normally returns one Ruby value. Application callers and code mode
+receive that value, while LittleGhost serializes it for the model. Use
+`Tool::Result` when the operation also produces files or media:
+
+```ruby
+def call(input)
+  report = Reports.build(input.fetch("period"))
+  LittleGhost::Tool::Result.new(
+    value: {rows: report.rows.length},
+    artifacts: [
+      LittleGhost::Artifact.new(
+        data: report.csv,
+        media_type: "text/csv",
+        name: "report.csv"
+      )
+    ]
+  )
+end
+```
+
+`Tool::Result#value` is the same plain Ruby value a Tool would otherwise return.
+Each inline `Artifact` has bytes, a MIME media type, and an optional name and
+metadata. Use `Artifact.deferred(reference:, media_type:, ...)` when another
+application service stores the bytes. The optional block passed to
+`Configuration#artifacts` receives the deferred Artifact and may use its
+application-defined `reference` to load the bytes later.
+
+Artifact handling is opt-in for the Runtime:
+
+```ruby
+LittleGhost.configure do |config|
+  config.workspace = {
+    provider: :directory,
+    root: "tmp/agent-runs",
+    paths: {artifacts: "artifacts"}
+  }
+  config.artifacts
+end
+```
+
+Once enabled, artifact handling covers three cases:
+
+- Input images and documents are stored so filesystem Tools and code mode can
+  read the same bytes. The model still receives only the original image or
+  document.
+- Tool artifacts are stored and returned to the model as images or documents.
+  The stored reference is shown only when the media cannot be included in the
+  model request.
+- Oversized successful Tool values are stored automatically. The model receives
+  a short preview and a reference instead of the complete value.
+
+The Tool's Ruby return value does not change. LittleGhost limits the size of
+each stored file, the total files and bytes stored for a Run, and the media
+sent in one model turn. If an oversized value cannot be stored within those
+limits, the application still receives the complete Ruby value and the model
+receives a short preview with a storage-limit notice.
+
+To load a deferred artifact, pass a block. It may return bytes, an inline
+Artifact with a final MIME type, or `nil` when the referenced file is no longer
+available:
+
+```ruby
+config.artifacts do |artifact, run:|
+  StoredFiles.read(artifact.reference, actor_id: run.invocation.actor_id)
+end
+```
+
+> **Safety note:** A deferred reference is data, not proof that the current
+> caller may read a file. Check it against identity established by the
+> application, restrict the storage service or network destination, and limit
+> the bytes fetched before returning them. LittleGhost applies its storage limit
+> after the resolver returns.
+
+Declaring the named Workspace path does not grant model access. When the Agent
+should read artifact references, grant the Sandbox read access to the
+`:artifacts` path and include a filesystem Tool. The model can list that path
+when a task genuinely needs a stored file; ordinary multimodal work does not
+need a second reference to media already in the conversation.
+
+## Let code mode compose the same capabilities
+
+Without code mode, the model chooses one Tool operation and LittleGhost returns
+the result before the model chooses the next step. Code mode lets the model
+write a small Ruby program that calls several of the same Tools, combines their
+results, and returns one useful value.
+
+Each call crosses back to the parent Ruby process. LittleGhost checks the schema
+and calls the Tool method there, so permission checks inside `#call` still
+apply. Code mode receives the Tool's Ruby return value, while artifacts return
+with the surrounding `exec` or `wait` result. Tool limits, callbacks, events,
+and tracing work the same way for direct and code-mode calls.
+
+Continue with [Structured Results and Content](structured_outputs_and_content.md)
+to give Agent responses a predictable shape and accept images or documents.
+For exact Tool DSL and result contracts, see `LittleGhost::Tool` and
+`LittleGhost::Tool::Binding`.

data/lib/little_ghost/ag_ui/adapter.rb

@@ -18,13 +18,13 @@ module LittleGhost
     # The adapter has no state between #stream calls, so one instance can
     # translate independent runs.
     #
-    # === Security and trust
+    # === Choose what the interface receives
     #
     # Provider plaintext reasoning becomes AG-UI reasoning events. Tool
     # arguments and results, invocation metadata, subagent events, trace context,
     # and selected error text also pass through without redaction. Authorize and
     # filter the complete stream before transport, and send it only to an
-    # interface trusted to display that data. Encrypted reasoning and provider
+    # interface intended to display that data. Encrypted reasoning and provider
     # continuity artifacts are never exposed here.
     class Adapter
       TERMINAL_EVENTS = %i[run_partial run_cancel run_stop run_error].freeze # :nodoc:

data/lib/little_ghost/agent/delegation.rb

@@ -22,7 +22,7 @@ module LittleGhost
     #
     # Tool overrides must be classes. A delegated agent otherwise receives only
     # its own declared tools; it does not inherit the parent's registry. The
-    # manager enforces its concurrency, identity, polling, and persistence bounds.
+    # manager enforces concurrency, identity, wait duration, and persistence bounds.
     module Delegation
       def self.included(base) # :nodoc:
         base.extend(ClassMethods)
@@ -40,7 +40,7 @@ module LittleGhost
         #   subagent_long_poll_duration() -> Float
         #   subagent_long_poll_duration(seconds) -> Float
         #
-        # The maximum long-poll duration used by subagent wait tools.
+        # How long +wait_for_subagents+ watches for progress before returning.
         #
         # The default comes from Subagents::Manager. Values must be positive,
         # finite numbers and are normalized to Float.

data/lib/little_ghost/agent/skills.rb

@@ -36,7 +36,12 @@ module LittleGhost
           end
           paths ||= binding.run.runtime.skill_paths
           catalog = LittleGhost::Skills::Catalog.new(
-            **configuration.merge(paths:, resource_root: binding.run&.runtime&.skill_resource_root)
+            **configuration.merge(
+              paths:,
+              resource_root: binding.run&.runtime&.skill_resource_root,
+              workspace: binding.workspace,
+              sandbox: binding.sandbox
+            )
           )
           return [] if catalog.names.empty?