little_ghost 0.1.0

data/lib/little_ghost/tools/filesystem.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Ready-made model-facing tools for filesystem, process, and planning work.
+  # Each tool uses the same binding and sandbox rules as an application tool.
+  module Tools
+    # Filesystem gives an agent read, list, write, and replace tools backed by the
+    # application's Sandbox. A read-only sandbox automatically exposes only the
+    # non-mutating tools.
+    #
+    #   binding = LittleGhost::Tool::Binding.new(sandbox: sandbox)
+    #   registry = LittleGhost::ToolRegistry.new(
+    #     [LittleGhost::Tools::Filesystem], binding: binding
+    #   )
+    #   registry.names # => ["read_file", "list_files"]
+    #
+    # === Security and trust
+    #
+    # These tools do not add isolation. The configured sandbox must enforce path
+    # containment, permissions, size limits, and cancellation.
+    class Filesystem
+      # Reads one UTF-8 text file through the configured sandbox.
+      class ReadFile < Tool
+        tool_name "read_file"
+        description "Read a UTF-8 text file within the configured workspace."
+        input_schema type: "object", properties: {path: {type: "string"}}, required: ["path"], additionalProperties: false
+
+        # Returns the UTF-8 text at <tt>input["path"]</tt> through the sandbox.
+        def call(input)
+          sandbox.read(input.fetch("path"), context:)
+        end
+      end
+
+      # Lists one directory through the configured sandbox.
+      class ListFiles < Tool
+        tool_name "list_files"
+        description "List files and directories within the configured workspace."
+        input_schema type: "object", properties: {path: {type: "string"}}, additionalProperties: false
+
+        # Returns the listing for <tt>input["path"]</tt>, or the workspace root
+        # when +path+ is omitted.
+        def call(input)
+          sandbox.list(input.fetch("path", "."), context:)
+        end
+      end
+
+      # Writes one UTF-8 text file through a writable sandbox.
+      class WriteFile < Tool
+        tool_name "write_file"
+        description "Write a UTF-8 text file within the configured writable workspace."
+        input_schema type: "object", properties: {
+          path: {type: "string"}, content: {type: "string"}
+        }, required: %w[path content], additionalProperties: false
+
+        # Writes <tt>input["content"]</tt> to <tt>input["path"]</tt> through the
+        # sandbox.
+        def call(input)
+          sandbox.write(input.fetch("path"), input.fetch("content"), context:)
+        end
+      end
+
+      # Replaces one unique text occurrence through a writable sandbox.
+      class ReplaceInFile < Tool
+        tool_name "replace_in_file"
+        description "Replace one unique occurrence of text in a UTF-8 file within a configured writable workspace."
+        input_schema type: "object", properties: {
+          path: {type: "string"}, old_text: {type: "string"}, new_text: {type: "string"}
+        }, required: %w[path old_text new_text], additionalProperties: false
+
+        # Replaces the one matching +old_text+ occurrence at +path+.
+        def call(input)
+          sandbox.replace(input.fetch("path"), input.fetch("old_text"), input.fetch("new_text"), context:)
+        end
+      end
+
+      class ExclusiveReadFile < ReadFile # :nodoc:
+        exclusive true
+      end
+
+      class ExclusiveListFiles < ListFiles # :nodoc:
+        exclusive true
+      end
+
+      class ExclusiveWriteFile < WriteFile # :nodoc:
+        exclusive true
+      end
+
+      class ExclusiveReplaceInFile < ReplaceInFile # :nodoc:
+        exclusive true
+      end
+
+      # Selects the tool classes allowed by +binding.sandbox+.
+      class << self
+        # Provides read tools for every sandbox and mutation tools only when the
+        # sandbox is writable.
+        def tools(binding)
+          [*read_tools, *(write_tools if binding.sandbox.writable?)]
+        end
+
+        private
+
+        def read_tools = [ReadFile, ListFiles]
+        def write_tools = [WriteFile, ReplaceInFile]
+      end
+
+      # Provides filesystem tools marked exclusive for shared workspace mutation.
+      # Read operations are also serialized so a batch cannot observe a concurrent
+      # write from another tool call in the same run.
+      class Exclusive < self
+        class << self
+          private
+
+          def read_tools = [ExclusiveReadFile, ExclusiveListFiles]
+          def write_tools = [ExclusiveWriteFile, ExclusiveReplaceInFile]
+        end
+      end
+    end
+  end
+end

data/lib/little_ghost/tools/shell.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LittleGhost
+  module Tools
+    # Shell lets an agent run one executable through the configured Sandbox. It
+    # accepts an argument vector, so model-supplied values are not interpreted as
+    # shell syntax.
+    #
+    # The child environment is cleared, runtime is limited to 30 seconds, and
+    # each output stream is limited to 1 MB. These defaults reduce accidental
+    # exposure but do not create an isolation boundary; the configured sandbox
+    # remains responsible for security.
+    class Shell < Tool
+      DEFAULT_TIMEOUT = 30 # :nodoc:
+      MAX_OUTPUT_BYTES = 1_000_000 # :nodoc:
+
+      tool_name "shell"
+      description "Run one executable with arguments in the configured workspace. Shell syntax is not interpreted."
+      input_schema type: "object", properties: {
+        command: {type: "array", items: {type: "string"}}
+      }, required: ["command"], additionalProperties: false
+
+      # Executes <tt>input["command"]</tt> and returns a JSON result containing
+      # standard output, standard error, exit status, and success.
+      def call(input)
+        result = sandbox.execute_program(
+          input.fetch("command"),
+          timeout: DEFAULT_TIMEOUT,
+          context:,
+          max_output_bytes: MAX_OUTPUT_BYTES,
+          environment: {},
+          inherit_environment: false
+        )
+        JSON.generate(
+          stdout: result.stdout,
+          stderr: result.stderr,
+          exit_status: result.exit_code,
+          success: result.success?
+        )
+      end
+    end
+  end
+end

data/lib/little_ghost/tools/write_todos.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Tools
+    # WriteTodos lets an agent share a live plan with the application and the
+    # person following its work. Add it like any other tool:
+    #
+    #   class ResearchAgent < LittleGhost::Agent
+    #     tools LittleGhost::Tools::WriteTodos
+    #   end
+    #
+    # Each execution replaces the full plan in RunContext state. Todo IDs remain stable across
+    # updates, statuses are +pending+, +in_progress+, or +completed+, and no more
+    # than one todo may be in progress. When no context is available, the tool
+    # retains fallback state on its instance.
+    class WriteTodos < Tool
+      tool_name "write_todos"
+      description <<~DESCRIPTION.strip
+        Replace the plan for meaningful multi-step work. Skip this for simple requests. Give the plan and every todo a
+        short user-facing title. Put longer private working notes in details. Publish the full list before substantive
+        work, allow at most one in-progress step, and replace the full list as work progresses. Preserve IDs for todos
+        that remain, update titles and statuses in place, never reuse an ID for a different todo, and remove todos that
+        no longer apply. Complete every remaining todo before the final response; use an empty list when no plan remains.
+      DESCRIPTION
+      input_schema(
+        type: "object",
+        properties: {
+          plan_title: {type: "string", minLength: 1, maxLength: 80, pattern: "^[^\\x00-\\x1f\\x7f]+$"},
+          todos: {
+            type: "array",
+            maxItems: 20,
+            items: {
+              type: "object",
+              properties: {
+                id: {type: "string", minLength: 1, maxLength: 64, pattern: "^[a-z0-9][a-z0-9_-]*$"},
+                title: {type: "string", minLength: 1, maxLength: 48, pattern: "^[^\\x00-\\x1f\\x7f]+$"},
+                status: {type: "string", enum: %w[pending in_progress completed]},
+                details: {type: ["string", "null"], maxLength: 4_000}
+              },
+              required: %w[id title status],
+              additionalProperties: false
+            }
+          }
+        },
+        required: %w[plan_title todos],
+        additionalProperties: false
+      )
+
+      # Trims user-facing titles before normal tool validation and execution.
+      def execute(input, context: nil)
+        super(normalize_titles(input), context:)
+      end
+
+      # Replaces the stored plan after enforcing progress and ID invariants.
+      def call(input)
+        todos = input.fetch("todos")
+        raise ToolError, "only one todo may be in progress" if todos.count { |todo| todo["status"] == "in_progress" } > 1
+
+        ids = todos.map { |todo| todo.fetch("id") }
+        raise ToolError, "todo IDs must be unique" unless ids.uniq.length == ids.length
+
+        state = context ? (context.state["little_ghost.plan"] ||= empty_plan) : (@fallback_state ||= empty_plan)
+        state.replace("plan_title" => input.fetch("plan_title"), "todos" => todos.map(&:dup))
+        state.dup
+      end
+
+      private
+
+      def normalize_titles(input)
+        return input unless input.is_a?(Hash)
+
+        normalized = input.dup
+        normalized["plan_title"] = normalized["plan_title"].strip if normalized["plan_title"].is_a?(String)
+        if normalized["todos"].is_a?(Array)
+          normalized["todos"] = normalized["todos"].map do |todo|
+            next todo unless todo.is_a?(Hash)
+
+            todo = todo.dup
+            todo["title"] = todo["title"].strip if todo["title"].is_a?(String)
+            todo
+          end
+        end
+        normalized
+      end
+
+      def empty_plan
+        {"plan_title" => nil, "todos" => []}
+      end
+    end
+  end
+end

data/lib/little_ghost/tools.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Loads LittleGhost's dependency-free filesystem and shell tool adapters.
+# Requiring +little_ghost+ alone does not load these model-facing tools.
+require_relative "tools/filesystem"
+require_relative "tools/shell"