samagotchi 0.8.1 → 0.10.0

data/lib/samagotchi/tool_call_parser.rb

@@ -1,33 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "model_profile"
-require_relative "tools/execute"
-require_relative "tools/read"
-require_relative "tools/write"
-require_relative "tools/memory"
-require_relative "tools/edit"
-require_relative "tools/task_create"
-require_relative "tools/task_get"
-require_relative "tools/task_list"
-require_relative "tools/task_stop"
-require_relative "tools/task_wait"
-require_relative "tools/web_fetch"
-require_relative "tools/register_reminder"
-require_relative "tools/cancel_reminder"
-require_relative "tools/list_reminders"
-require_relative "tools/list_sessions"
-require_relative "tools/send_note"
-require_relative "tools/delegate"
-require_relative "tools/delegate_result"
-require_relative "tools/ask_user_question"
 require_relative "tools/args"
+require_relative "tools/ask_user_question"
+require_relative "tools/builtin_calls"
 
 module Samagotchi
-  # Per-profile strategy for parsing raw model output into internal tool
-  # calls ({name:, content:, path:, scope:, ...}) and stripping per-profile
-  # thought blocks. KernelLoop delegates here so it no longer carries dual
-  # Gemma/Qwen parse code paths; the ModelProfile remains the source of truth
-  # for call/thought delimiter tokens.
+  # Per-profile strategy for reading tool calls out of raw model output and
+  # stripping per-profile thought blocks. #read gives each call as
+  # {name:, args:, raw:} (its wire format read, nothing more); #parse builds
+  # them into internal calls with Tools::BuiltinCalls, as the chat path
+  # does. The ModelProfile remains the source of truth for call/thought
+  # delimiter tokens.
   class ToolCallParser
     # @param profile [ModelProfile]
     # @return [Gemma, Qwen]
@@ -67,8 +51,13 @@ module Samagotchi
 
       # Parse canonical Gemma 4 tool calls:
       #   <|tool_call>call:NAME{params}<tool_call|>
-      # Uses String#index for outer delimiters (no backtracking risk).
       def parse(text)
+        read(text).map { |call| Tools::BuiltinCalls.build(call[:name], call[:args], raw: call[:raw]) }
+      end
+
+      # Each tool call as {name:, args:, raw:}, unbuilt.
+      # Uses String#index for outer delimiters (no backtracking risk).
+      def read(text)
         results = []
 
         pos = 0
@@ -82,7 +71,7 @@ module Samagotchi
             name       = m[1]
             params_raw = body[m.end(0)..]
             params_raw = params_raw[0..-2] if params_raw.end_with?("}")
-            results << native_call(name, params_raw.strip)
+            results << read_call(name, params_raw.strip)
           end
           pos = close_pos + @tool_call_close.length
         end
@@ -154,155 +143,47 @@ module Samagotchi
         str.gsub(@string_delim, "")
       end
 
-      # Map native {key: "value"} params to the internal call hash.
-      # Uses well-known named params for each tool; falls back to params_raw if
-      # no recognised param is present.
+      # One call's {key: "value"} params as args (string keys).
+      #
+      # A built-in's params come from the flat scan (extract_native_params):
+      # strings, quotes unescaped its own way. A tool that isn't built in
+      # gets its body read as values (Tools::Args.parse_gemma: numbers,
+      # booleans, lists, objects), the flat scan when that fails, and the
+      # raw text as content for the unknown-tool error.
       #
       # The model sometimes omits quotes and/or the space after the colon, e.g.
       #   {command:ruby -e 'puts 1'}  instead of  {command: "ruby -e 'puts 1'"}
-      # In that case extract_native_params finds nothing and params_raw still
-      # contains the "key:" prefix. strip_param_prefix removes it so the actual
-      # command/path value is passed to the tool rather than the raw fragment.
+      # In that case extract_native_params finds nothing; the main argument
+      # (BuiltinCalls row's fallback) is then the body after a "key:" prefix,
+      # or the whole body.
       #
       # Gemma 4 may also use its <|"|> string delimiter token instead of plain
-      # quotes. strip_gemma_delimiters is applied to all fallback values so that
-      # <|"|>value<|"|> is cleaned to just "value" before being dispatched.
-      def native_call(name, params_raw)
-        params = extract_native_params(params_raw)
+      # quotes; it is stripped from every value but file text, old/new, env
+      # and options.
+      def read_call(name, params_raw)
+        row = Tools::BuiltinCalls.row(name)
+        unless row
+          args = Tools::Args.parse_gemma(params_raw, @string_delim) || extract_native_params(params_raw)
+          return { name: name, args: args, raw: strip_gemma_delimiters(params_raw) }
+        end
 
-        case name
-        when Tools::Execute::NAME
-          content = params["command"] ||
-                    strip_param_prefix(params_raw, "command") ||
-                    params_raw
-          { name: name, content: strip_gemma_delimiters(content), path: nil, scope: nil }
-        when Tools::Read::NAME
-          content = params["path"] ||
-                    strip_param_prefix(params_raw, "path") ||
-                    params_raw
-          {
-            name: name,
-            content: strip_gemma_delimiters(content),
-            path: nil,
-            scope: nil,
-            start_line: params["start_line"],
-            end_line: params["end_line"]
-          }
-        when Tools::Write::NAME
-          { name: name, content: params["content"] || "", path: params["path"], scope: nil }
-        when Tools::MemoryRead::NAME
-          content = params["name"] ||
-                    strip_param_prefix(params_raw, "name") ||
-                    params_raw
-          { name: name, content: strip_gemma_delimiters(content), path: nil, scope: params["scope"] }
-        when Tools::MemoryWrite::NAME
-          # The declaration uses "name" (required) and "scope" (required).
-          entry_name = params["name"] || ""
-          { name: name, content: params["content"] || "", path: entry_name, scope: params["scope"], description: params["description"] ? strip_gemma_delimiters(params["description"]) : nil,
-            current_model_only: params["current_model_only"] }
-        when Tools::Edit::NAME
-          old_text = params["old_text"] || params["old"] || ""
-          new_text = params["new_text"] || params["new"] || ""
-          content  = "<old>#{old_text}</old><new>#{new_text}</new>"
-          {
-            name: name,
-            content: content,
-            path: params["path"],
-            scope: nil,
-            start_line: params["start_line"],
-            end_line: params["end_line"]
-          }
-        when Tools::TaskCreate::NAME
-          command = params["command"] ||
-                    strip_param_prefix(params_raw, "command") ||
-                    params_raw
-          {
-            name: name,
-            content: strip_gemma_delimiters(command),
-            path: nil,
-            scope: nil,
-            cwd: params["cwd"],
-            env: params["env"]
-          }
-        when Tools::TaskGet::NAME, Tools::TaskStop::NAME
-          task_id = params["id"] ||
-                    params["task_id"] ||
-                    strip_param_prefix(params_raw, "id") ||
-                    strip_param_prefix(params_raw, "task_id") ||
-                    params_raw
-          {
-            name: name,
-            content: strip_gemma_delimiters(task_id),
-            path: nil,
-            scope: nil
-          }
-        when Tools::TaskWait::NAME
-          task_id = params["id"] ||
-                    params["task_id"] ||
-                    strip_param_prefix(params_raw, "id") ||
-                    strip_param_prefix(params_raw, "task_id") ||
-                    params_raw
-          {
-            name: name,
-            content: strip_gemma_delimiters(task_id),
-            path: nil,
-            scope: nil,
-            timeout: params["timeout"],
-            tail_lines: params["tail_lines"],
-            done_pattern: params["done_pattern"]
-          }
-        when Tools::TaskList::NAME
-          { name: name, content: "", path: nil, scope: nil }
-        when Tools::WebFetch::NAME
-          content = params["url"] ||
-                    strip_param_prefix(params_raw, "url") ||
-                    params_raw
-          { name: name, content: strip_gemma_delimiters(content), path: nil, scope: nil }
-        when Tools::RegisterReminder::NAME
-          content = params["name"] || strip_param_prefix(params_raw, "name") || params_raw
-          {
-            name: name,
-            content: strip_gemma_delimiters(content),
-            path: nil,
-            scope: nil,
-            description: params["description"] || "",
-            interval_minutes: params["interval_minutes"] || "1"
-          }
-        when Tools::CancelReminder::NAME
-          content = params["name"] || strip_param_prefix(params_raw, "name") || params_raw
-          { name: name, content: strip_gemma_delimiters(content), path: nil, scope: nil }
-        when Tools::ListReminders::NAME
-          { name: name, content: "", path: nil, scope: nil }
-        when Tools::ListSessions::NAME
-          cwd = params["cwd"] || strip_param_prefix(params_raw, "cwd")
-          { name: name, content: "", path: nil, scope: nil, cwd: cwd && strip_gemma_delimiters(cwd) }
-        when Tools::SendNote::NAME
-          { name: name, content: strip_gemma_delimiters(params["text"].to_s), path: nil, scope: nil,
-            session: strip_gemma_delimiters(params["session"].to_s) }
-        when Tools::Delegate::NAME
-          task = params["task"] || strip_param_prefix(params_raw, "task") || params_raw
-          { name: name, content: strip_gemma_delimiters(task.to_s), path: nil, scope: nil,
-            model: params["model"] && strip_gemma_delimiters(params["model"]),
-            session: params["session"] && strip_gemma_delimiters(params["session"]),
-            wait: params["wait"], timeout: params["timeout"] }
-        when Tools::DelegateResult::NAME
-          { name: name, content: "", path: nil, scope: nil,
-            session: params["session"] && strip_gemma_delimiters(params["session"]), timeout: params["timeout"] }
-        when Tools::AskUserQuestion::NAME
-          { name: name, content: params["question"] ? strip_gemma_delimiters(params["question"]) : strip_gemma_delimiters(params_raw),
-            path: nil, scope: nil,
-            question: params["question"] ? strip_gemma_delimiters(params["question"]) : strip_gemma_delimiters(params_raw),
-            options: parse_ask_options(params, params_raw),
-            header: params["header"] ? strip_gemma_delimiters(params["header"]) : nil,
-            multi_select: params["multi_select"],
-            allow_freeform: params["allow_freeform"] }
-        else
-          # A registry (plugin) tool, or an unknown one: its arguments as a
-          # Hash on args: (typed by the schema at dispatch), and the raw text
-          # as content for the unknown-tool error.
-          args = Tools::Args.parse_gemma(params_raw, @string_delim) || params
-          { name: name, content: strip_gemma_delimiters(params_raw), path: nil, scope: nil, args: args }
+        params = extract_native_params(params_raw)
+        args = params.to_h do |key, value|
+          [key, value.is_a?(String) && !row.verbatim_key?(key) ? strip_gemma_delimiters(value) : value]
         end
+        fill_main_argument(row, args, params_raw)
+        args["options"] = parse_ask_options(params, params_raw) if row.options
+        { name: name, args: args, raw: params_raw }
+      end
+
+      # The row's main argument from a body the scan didn't find it in.
+      def fill_main_argument(row, args, params_raw)
+        return unless row.fallback
+        return if row.fallback_keys.any? { |key| args.key?(key) }
+
+        value = row.fallback_keys.lazy.map { |key| strip_param_prefix(params_raw, key) }.find(&:itself) unless row.fallback == :raw
+        value ||= params_raw unless row.fallback == :prefix
+        args[row.fallback_key || row.content_keys.first] = strip_gemma_delimiters(value) if value
       end
 
       def parse_ask_options(params, params_raw)
@@ -424,6 +305,12 @@ module Samagotchi
       end
 
       def parse(text)
+        read(text).map { |call| Tools::BuiltinCalls.build(call[:name], call[:args], raw: call[:raw]) }
+      end
+
+      # Each <tool_call> block as {name:, args:, raw:}: its <parameter=…>
+      # (or <arg_key>/<arg_value>) text by lowercased key, unbuilt.
+      def read(text)
         results = []
 
         pos = 0
@@ -438,7 +325,7 @@ module Samagotchi
           body = text[body_start...close_pos]
           if (name = qwen_function_name(body))
             params = qwen_params(body)
-            results << qwen_call_to_internal(name, params)
+            results << { name: name, args: params, raw: params.to_s }
           end
           pos = close_pos + tool_close.length
         end
@@ -509,129 +396,6 @@ module Samagotchi
 
         nil
       end
-
-      def qwen_call_to_internal(name, params)
-        case name
-        when Tools::Execute::NAME
-          { name: name, content: qwen_param_value(params, "command"), path: nil, scope: nil }
-        when Tools::Read::NAME
-          {
-            name: name,
-            content: qwen_param_value(params, "path"),
-            path: nil,
-            scope: nil,
-            start_line: qwen_param_value(params, "start_line"),
-            end_line: qwen_param_value(params, "end_line")
-          }
-        when Tools::Write::NAME
-          content = qwen_param_value(params, "content", "text", strip: false)
-          { name: name, content: content, path: qwen_param_value(params, "path"), scope: nil }
-        when Tools::MemoryRead::NAME
-          memory_name = qwen_param_value(params, "name")
-          { name: name, content: memory_name, path: nil, scope: qwen_param_value(params, "scope") }
-        when Tools::MemoryWrite::NAME
-          entry_name = qwen_param_value(params, "name")
-          content = qwen_param_value(params, "content", "text", "body", "value", strip: false)
-          { name: name, content: content, path: entry_name, scope: qwen_param_value(params, "scope"), description: qwen_param_value(params, "description"),
-            current_model_only: qwen_param_value(params, "current_model_only") }
-        when Tools::Edit::NAME
-          old_text = qwen_param_value(params, "old_text", "old", strip: false)
-          new_text = qwen_param_value(params, "new_text", "new", strip: false)
-          content  = "<old>#{old_text}</old><new>#{new_text}</new>"
-          {
-            name: name,
-            content: content,
-            path: qwen_param_value(params, "path"),
-            scope: nil,
-            start_line: qwen_param_value(params, "start_line"),
-            end_line: qwen_param_value(params, "end_line")
-          }
-        when Tools::TaskCreate::NAME
-          {
-            name: name,
-            content: qwen_param_value(params, "command"),
-            path: nil,
-            scope: nil,
-            cwd: qwen_param_value(params, "cwd"),
-            env: qwen_param_value(params, "env", strip: false)
-          }
-        when Tools::TaskGet::NAME, Tools::TaskStop::NAME
-          {
-            name: name,
-            content: qwen_param_value(params, "id", "task_id"),
-            path: nil,
-            scope: nil
-          }
-        when Tools::TaskWait::NAME
-          {
-            name: name,
-            content: qwen_param_value(params, "id", "task_id"),
-            path: nil,
-            scope: nil,
-            timeout: qwen_param_value(params, "timeout"),
-            tail_lines: qwen_param_value(params, "tail_lines"),
-            done_pattern: qwen_param_value(params, "done_pattern")
-          }
-        when Tools::TaskList::NAME
-          { name: name, content: "", path: nil, scope: nil }
-        when Tools::WebFetch::NAME
-          { name: name, content: qwen_param_value(params, "url"), path: nil, scope: nil }
-        when Tools::RegisterReminder::NAME
-          {
-            name: name,
-            content: qwen_param_value(params, "name"),
-            path: nil,
-            scope: nil,
-            description: qwen_param_value(params, "description"),
-            interval_minutes: qwen_param_value(params, "interval_minutes")
-          }
-        when Tools::CancelReminder::NAME
-          { name: name, content: qwen_param_value(params, "name"), path: nil, scope: nil }
-        when Tools::ListReminders::NAME
-           { name: name, content: "", path: nil, scope: nil }
-        when Tools::ListSessions::NAME
-          { name: name, content: "", path: nil, scope: nil, cwd: qwen_param_value(params, "cwd") }
-        when Tools::SendNote::NAME
-          { name: name, content: qwen_param_value(params, "text"), path: nil, scope: nil,
-            session: qwen_param_value(params, "session") }
-        when Tools::Delegate::NAME
-          { name: name, content: qwen_param_value(params, "task"), path: nil, scope: nil,
-            model: qwen_param_value(params, "model"), session: qwen_param_value(params, "session"),
-            wait: qwen_param_value(params, "wait"), timeout: qwen_param_value(params, "timeout") }
-        when Tools::DelegateResult::NAME
-          { name: name, content: "", path: nil, scope: nil,
-            session: qwen_param_value(params, "session"), timeout: qwen_param_value(params, "timeout") }
-        when Tools::AskUserQuestion::NAME
-           opts_raw = qwen_param_value(params, "options", strip: false)
-           opts = qwen_ask_options(opts_raw)
-           {
-             name: name,
-             content: qwen_param_value(params, "question"),
-             path: nil, scope: nil,
-             question: qwen_param_value(params, "question"),
-             options: opts,
-             header: qwen_param_value(params, "header"),
-             multi_select: qwen_param_value(params, "multi_select"),
-             allow_freeform: qwen_param_value(params, "allow_freeform")
-           }
-        else
-           # A registry (plugin) tool, or an unknown one: the parameters as
-           # given (text; typed by the schema at dispatch).
-           { name: name, content: params.to_s, path: nil, scope: nil, args: params }
-        end
-      end
-
-      def qwen_param_value(params, *keys, strip: true)
-        value = keys.lazy.map { |key| params[key] }.find { |candidate| !candidate.nil? }
-        return "" if value.nil?
-
-        strip ? value.to_s.strip : value.to_s
-      end
-
-      def qwen_ask_options(raw)
-        norm = Samagotchi::Tools::AskUserQuestion.normalize_options_lenient(raw)
-        norm.empty? ? nil : norm
-      end
     end
   end
 end

data/lib/samagotchi/tool_declarations.rb

@@ -123,7 +123,7 @@ module Samagotchi
       },
       {
         name: "memory_write",
-        description: "Write or update a memory entry in scoped memories. Scope is required: project or system. Use the `name` parameter for the entry name (use `name`, NOT `path` — the file tools use `path`); each scope's index.md is auto-maintained (one managed line per entry); use name \"index\" to write the index file verbatim. If the user asks to save guidance for the current model only, pass current_model_only: true to save a model-specific overlay.",
+        description: "Write or update a memory entry in scoped memories. Scope is required: project or system. Use the `name` parameter for the entry name (use `name`, NOT `path` — the file tools use `path`); each scope's index.md is auto-maintained (one managed line per entry); use name \"index\" to write the index file verbatim. For a small change to an existing memory (a step, a line), `edit` its file (<scope dir>/<name>.md) instead of rewriting it all; its index line is refreshed either way. If the user asks to save guidance for the current model only, pass current_model_only: true to save a model-specific overlay.",
         parameters: {
           type: "object",
           properties: {

data/lib/samagotchi/tool_runner.rb

@@ -6,6 +6,7 @@ require_relative "vision_context"
 require_relative "log"
 require_relative "edit_preview"
 require_relative "tools/tool_path"
+require_relative "memory_bundle/index_sync"
 
 module Samagotchi
   # The single per-call path both loops use: the tool_call_started and
@@ -67,6 +68,7 @@ module Samagotchi
       before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
       result = verdict.deny? ? denied(call, verdict) : dispatch(call)
       diff = file_change(call, before)
+      refresh_memory_index(call) if diff
       result = approved(result, verdict) if verdict.allow? && verdict.decided_by
       result, images = attach_images(call, result) if result[:images]
 
@@ -117,6 +119,12 @@ module Samagotchi
       nil
     end
 
+    # A write/edit that changed a memory's file refreshes its index line,
+    # as memory_write does (MemoryBundle::IndexSync; a no-op elsewhere).
+    def refresh_memory_index(call)
+      MemoryBundle::IndexSync.refresh(Tools::ToolPath.normalize(call[:path]))
+    end
+
     # A tool's output can hold bytes that aren't UTF-8 (`printf '\xff'`, a
     # binary file). They become "?" here, before the output reaches the
     # conversation, the events and the saved session: JSON.generate raises

data/lib/samagotchi/tools/builtin_calls.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "../tool_declarations"
+require_relative "ask_user_question"
+
+module Samagotchi
+  module Tools
+    # The one map from a parsed tool call ({name, args}) to the internal call
+    # the built-in handlers, hooks, guardrails and bundles read:
+    #
+    #   { name:, content:, path:, scope:, <each other schema field>: }
+    #
+    # Each parser (Gemma, Qwen, the chat path) only reads its wire format
+    # into string-keyed args; this table says where each argument goes. It is
+    # derived from ToolDeclarations::TOOL_SCHEMAS: a property goes to the
+    # field of its own name, unless OVERRIDES puts it in content: (the
+    # tool's main argument) or path:. A new parameter is a schema property
+    # and the handler reading it.
+    #
+    # A tool that is not built in keeps its arguments whole on args: (typed
+    # by its schema at dispatch, Tools::Args) with +raw+ as its content.
+    module BuiltinCalls
+      # Per tool, what the schema alone doesn't say:
+      #   content:  the property (or ordered list of keys to try) that fills
+      #             content:; absent, content: is "" (the handlers take a
+      #             String)
+      #   path:     the property that fills path: (otherwise "path" itself)
+      #   also:     a property that fills content: and keeps its own field
+      #   aliases:  other keys a model uses for a property, tried after it
+      #   verbatim: values passed as given (file text, old/new, env,
+      #             options); every other String value is stripped
+      #   fallback: how Gemma fills the main argument from a body it could
+      #             not read as key:value pairs (see ToolCallParser::Gemma)
+      #   options:  ask_user_question's options, normalized
+      OVERRIDES = {
+        "execute" => { content: "command", fallback: :prefix_or_raw },
+        "read" => { content: "path", fallback: :prefix_or_raw },
+        "write" => { verbatim: %w[content], aliases: { "content" => %w[text] } },
+        "memory_read" => { content: "name", fallback: :prefix_or_raw },
+        "memory_write" => { path: "name", verbatim: %w[content], aliases: { "content" => %w[text body value] } },
+        "edit" => { verbatim: %w[old_text new_text], aliases: { "old_text" => %w[old], "new_text" => %w[new] } },
+        "task_create" => { content: "command", verbatim: %w[env], fallback: :prefix_or_raw },
+        "task_get" => { content: %w[id task_id], fallback: :prefix_or_raw },
+        "task_stop" => { content: %w[id task_id], fallback: :prefix_or_raw },
+        "task_wait" => { content: %w[id task_id], fallback: :prefix_or_raw },
+        "web_fetch" => { content: "url", fallback: :prefix_or_raw },
+        "register_reminder" => { content: "name", fallback: :prefix_or_raw },
+        "cancel_reminder" => { content: "name", fallback: :prefix_or_raw },
+        "list_sessions" => { fallback: :prefix, fallback_key: "cwd" },
+        "send_note" => { content: "text" },
+        "delegate" => { content: "task", fallback: :prefix_or_raw },
+        "ask_user_question" => { content: "question", also: %w[question], verbatim: %w[options], options: true,
+                                 fallback: :raw }
+      }.freeze
+
+      # One built-in's mapping, resolved from its schema and OVERRIDES.
+      Row = Data.define(:name, :content_keys, :path_key, :fields, :aliases, :verbatim, :fallback, :fallback_key,
+                        :options) do
+        # The keys to try for +key+, in order.
+        def keys_for(key) = [key, *aliases.fetch(key, [])]
+
+        # The keys Gemma's fallback may find as a "key:" prefix.
+        def fallback_keys = fallback_key ? [fallback_key] : content_keys.flat_map { |key| keys_for(key) }
+
+        # Whether a given +key+ (a property or one of its aliases) is
+        # passed as given.
+        def verbatim_key?(key) = verbatim.any? { |property| keys_for(property).include?(key) }
+      end
+
+      module_function
+
+      # @return [Hash{String => Row}]
+      def rows
+        @rows ||= ToolDeclarations::TOOL_SCHEMAS.to_h { |schema| [schema[:name], row_for(schema)] }.freeze
+      end
+
+      def row_for(schema)
+        name = schema[:name]
+        o = OVERRIDES.fetch(name, {})
+        properties = schema.dig(:parameters, :properties).keys.map(&:to_s)
+        content_keys = Array(o[:content])
+        path_key = o[:path] || ("path" if properties.include?("path") && !content_keys.include?("path"))
+        taken = content_keys + [path_key].compact - Array(o[:also])
+        fields = properties - taken
+        # content: may list a model's other spelling (task_wait's "id"), so
+        # one of its keys must be a property; the rest must all be.
+        unknown = ([path_key].compact + Array(o[:verbatim]) + Array(o[:also]) + o.fetch(:aliases, {}).keys) - properties
+        unknown << content_keys.join("/") unless content_keys.empty? || content_keys.intersect?(properties)
+        raise ArgumentError, "#{name}: overrides name no schema property: #{unknown.join(', ')}" unless unknown.empty?
+        raise ArgumentError, "#{name}: a property would replace the call's name" if fields.include?("name")
+
+        Row.new(name: name, content_keys: content_keys, path_key: path_key, fields: fields,
+                aliases: o.fetch(:aliases, {}), verbatim: Array(o[:verbatim]), fallback: o[:fallback],
+                fallback_key: o[:fallback_key], options: o.fetch(:options, false))
+      end
+
+      # @return [Row, nil]
+      def row(name) = rows[name.to_s]
+
+      def builtin?(name) = rows.key?(name.to_s)
+
+      # The internal call for a parsed one.
+      # @param name [String]
+      # @param args [Hash] string keys, as the model gave them
+      # @param raw [String, nil] the call's text, the content of a tool
+      #   that isn't built in
+      # @return [Hash]
+      def build(name, args, raw: nil)
+        name = name.to_s
+        args = args.is_a?(Hash) ? args.transform_keys(&:to_s) : {}
+        row = row(name)
+        return passthrough(name, args, raw) unless row
+
+        call = { name: name, content: "", path: nil, scope: nil }
+        call[:content] = content_value(row, args)
+        call[:path] = value(row, args, row.path_key) if row.path_key
+        row.fields.each { |key| call[key.to_sym] = value(row, args, key) }
+        call[:options] = options(call[:options]) if row.options
+        call
+      end
+
+      def content_value(row, args)
+        found = row.content_keys.lazy.map { |key| value(row, args, key) }.find { |v| !v.nil? }
+        found.nil? ? "" : found.to_s
+      end
+
+      # The first given value among +key+ and its aliases, stripped unless
+      # verbatim; nil when none is given.
+      def value(row, args, key)
+        found = row.keys_for(key).lazy.map { |k| args[k] }.find { |v| !v.nil? }
+        found.is_a?(String) && !row.verbatim.include?(key) ? found.strip : found
+      end
+
+      # Normalized when they read as options, else as given (the question
+      # card's validate reads them again).
+      def options(raw)
+        normalized = AskUserQuestion.normalize_options_lenient(raw)
+        normalized.empty? ? raw : normalized
+      end
+
+      def passthrough(name, args, raw)
+        { name: name, content: raw.nil? ? args.values.join(" ") : raw.to_s, path: nil, scope: nil, args: args }
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/builtins.rb

@@ -66,7 +66,8 @@ module Samagotchi
           Read.call(call[:content], start_line: call[:start_line], end_line: call[:end_line])
         end,
         Edit::NAME => lambda do |call, _kctx|
-          Edit.call(call[:content], path: call[:path], start_line: call[:start_line], end_line: call[:end_line])
+          Edit.call(path: call[:path], old_text: call[:old_text], new_text: call[:new_text],
+                    start_line: call[:start_line], end_line: call[:end_line])
         end,
         TaskCreate::NAME => lambda do |call, kctx|
           next Execute::NOT_RUN_ON_STOP if cancelled_proc(kctx).call