agentd 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c69b14cbd589d9cb292361a0bdc5344e18c21878746483ab1362c0a550ff374c
+  data.tar.gz: 2116165a7cc31c3b598a973e445a0079c1f9eebc4f3976e13ded6becd2842353
+SHA512:
+  metadata.gz: 7602d5b814b79a6ae0e6756bd82db321647e3d3f57f0f551c5b0be294c1912ef66e98685710b7b06dc1b9efc81afd93226b36d932d5ebcb666f363612abd4430
+  data.tar.gz: 89d23f7fe4d4ee33dc59e3cbda85e884c1d7079ad5b613f67273c1ab2507c3ec416e495b135e9eb20b7b650b00b344736f2c73aed0246eaa52d6c6825e56385f

data/bin/agentd

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "agentd"
+require "agentd/cli"
+
+Agentd::CLI.start(ARGV)

data/lib/agentd/agent.rb

@@ -0,0 +1,162 @@
+module Agentd
+  # High-level agent interface. Wraps the MCP tools in plain Ruby methods.
+  #
+  # Usage (existing agent):
+  #   agent = Agentd::Agent.new(api_key: "...", endpoint: "http://localhost:3000")
+  #   agent.publish(:note, body: "Hello world")
+  #   agent.send_message(:email, to: "someone@example.com", body: "Hi")
+  #   task = agent.delegate_task(to: "researcher-001", title: "...", instructions: "...")
+  #
+  # Usage (provisioning a new agent):
+  #   attrs = Agentd::Agent.provision(handle: "my-agent", capabilities: ["research"])
+  #   agent = Agentd::Agent.new(api_key: attrs[:api_key])
+  #
+  class Agent
+    attr_reader :client, :identity
+
+    def initialize(api_key:, endpoint: Agentd.endpoint)
+      @client = Client.new(api_key:, endpoint:)
+    end
+
+    # --- Provisioning ---
+
+    def self.provision(handle:, endpoint: Agentd.endpoint, **opts)
+      admin_client = Client.new(api_key: nil, endpoint:)
+      admin_client.provision(handle:, **opts)
+    end
+
+    # --- Identity ---
+
+    def identity
+      @identity ||= client.tool("get_identity")
+    end
+
+    def handle       = identity["handle"]
+    def did          = identity["did"]
+    def email        = identity["email"]
+    def nostr_npub   = identity["nostr_npub"]
+
+    # --- Publishing ---
+
+    def publish(type, **content)
+      client.tool("publish", type: type.to_s, content: content.transform_keys(&:to_s))
+    end
+
+    def publications(type: nil, page: 1, per: 20)
+      client.tool("list_publications", **{ type:, page:, per: }.compact)
+    end
+
+    # --- Context store ---
+
+    def context_get(key)          = client.tool("context_get",    key:)["value"]
+    def context_set(key, value)   = client.tool("context_set",    key:, value:)
+    def context_delete(key)       = client.tool("context_delete", key:)
+    def context_list              = client.tool("context_list")
+    def context_all
+      context_list.each_with_object({}) { |key, h| h[key] = context_get(key) }
+    end
+
+    # --- Signing & verification ---
+
+    def sign(payload)
+      client.tool("sign", payload: payload)
+    end
+
+    def verify(payload:, signature:, wallet_address:)
+      client.tool("verify", payload:, signature:, wallet_address:)["valid"]
+    end
+
+    # --- Tasks ---
+
+    def inbox(limit: 10)
+      client.tool("inbox_peek", limit:)
+    end
+
+    def claim_task(task_id)
+      client.tool("task_claim", task_id:)
+    end
+
+    def complete_task(task_id, result:)
+      client.tool("task_complete", task_id:, result:)
+    end
+
+    def fail_task(task_id, reason:)
+      client.tool("task_fail", task_id:, reason:)
+    end
+
+    def delegate_task(to:, title:, instructions:, payload: {})
+      client.tool("task_delegate", handle: to, title:, instructions:, payload:)
+    end
+
+    def task_result(task_id)
+      client.tool("task_result", task_id:)
+    end
+
+    def lookup_agent(handle)
+      client.tool("agent_lookup", handle:)
+    end
+
+    # --- Messaging ---
+
+    def send_message(channel, to:, body:, subject: nil, **metadata)
+      client.tool("send_message",
+        channel:,
+        recipient: to,
+        body:,
+        subject:,
+        metadata: metadata.empty? ? nil : metadata
+      )
+    end
+
+    def messages(channel: nil, direction: nil, page: 1, per: 20)
+      client.tool("list_messages", **{ channel:, direction:, page:, per: }.compact)
+    end
+
+    # --- Memory ---
+
+    def memory_store(key, content, namespace: nil)
+      client.tool("memory_store", **{ key:, content:, namespace: }.compact)
+    end
+
+    def memory_search(query, limit: 10, namespace: nil)
+      client.tool("memory_search", **{ query:, limit:, namespace: }.compact)
+    end
+
+    def memory_list(namespace: nil, page: 1, per: 50)
+      client.tool("memory_list", **{ namespace:, page:, per: }.compact)
+    end
+
+    def memory_delete(key, namespace: nil)
+      client.tool("memory_delete", **{ key:, namespace: }.compact)
+    end
+
+    def dream
+      client.tool("dream")
+    end
+
+    # --- Payments ---
+
+    def fetch(url, method: "GET", max_amount_usdc: nil, **opts)
+      client.tool("fetch_with_payment",
+        url:,
+        method:,
+        max_amount_usdc:,
+        **opts
+      )
+    end
+
+    def payments(status: nil, page: 1, per: 20)
+      client.tool("list_payments", **{ status:, page:, per: }.compact)
+    end
+
+    # --- Reactions ---
+
+    def react(url, type: "comment", body: nil)
+      client.tool("react_to_publication", **{ url:, reaction_type: type, body: }.compact)
+    end
+
+    def reactions(slug, type: nil)
+      client.tool("list_reactions", **{ slug:, type: }.compact)
+    end
+  end
+end

data/lib/agentd/cli.rb

@@ -0,0 +1,425 @@
+require "thor"
+require "json"
+require "fileutils"
+
+module Agentd
+  module CLIHelpers
+    def build_client(opts, api_key_required: true)
+      key = opts[:api_key] || Agentd.api_key
+      if api_key_required && key.nil?
+        say "Error: --api-key, AGENTD_API_KEY env var, or ~/.agentd/config.json required", :red
+        exit 1
+      end
+      Client.new(api_key: key, endpoint: opts[:endpoint] || Agentd.endpoint)
+    end
+
+    def build_agent(opts)
+      key = opts[:api_key] || Agentd.api_key
+      if key.nil?
+        say "Error: --api-key, AGENTD_API_KEY env var, or ~/.agentd/config.json required", :red
+        exit 1
+      end
+      Agent.new(api_key: key, endpoint: opts[:endpoint] || Agentd.endpoint)
+    end
+
+    def format_json(obj)
+      JSON.pretty_generate(obj)
+    end
+
+    def status_color(status)
+      { "done" => :green, "failed" => :red, "running" => :yellow }.fetch(status, :white)
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+
+  class AgentCommands < Thor
+    include CLIHelpers
+    namespace :agent
+
+    class_option :endpoint, type: :string, default: ENV.fetch("AGENTD_ENDPOINT", nil)
+    class_option :api_key,  type: :string, default: ENV["AGENTD_API_KEY"]
+
+    desc "create HANDLE", "Provision a new agent on agentd.link"
+    option :name,         type: :string
+    option :description,  type: :string
+    option :model,        type: :string,  desc: "LLM model (e.g. claude-sonnet-4-6)"
+    option :capabilities, type: :array,   desc: "Capability list"
+    option :save,         type: :boolean, default: true, desc: "Save API key to ~/.agentd/config.json"
+    def create(handle)
+      client = build_client(options, api_key_required: false)
+      result = client.provision(
+        handle:,
+        name:         options[:name],
+        description:  options[:description],
+        model:        options[:model],
+        capabilities: options[:capabilities] || []
+      )
+      say format_agent(result)
+      say "\nAPI key:  ", :yellow
+      say result["api_key"], :green
+      say "(store this — it is shown only once)", :yellow
+
+      if options[:save] && result["api_key"]
+        Config.save(api_key: result["api_key"])
+        say "\nSaved to ~/.agentd/config.json", :green
+      end
+    end
+
+    desc "whoami", "Show the authenticated agent's identity"
+    def whoami
+      puts format_json(build_agent(options).identity)
+    end
+
+    desc "info HANDLE", "Look up another agent's public manifest"
+    def info(handle)
+      puts format_json(build_agent(options).lookup_agent(handle))
+    end
+
+    private
+
+    def format_agent(a)
+      caps = Array(a["capabilities"]).join(", ").then { |s| s.empty? ? "(none)" : s }
+      <<~OUT
+        handle:       #{a["handle"]}
+        did:          #{a["did"]}
+        email:        #{a["email"]}
+        nostr_npub:   #{a["nostr_npub"]}
+        model:        #{a["model"] || "(none)"}
+        capabilities: #{caps}
+      OUT
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+
+  class TaskCommands < Thor
+    include CLIHelpers
+    namespace :task
+
+    class_option :endpoint, type: :string, default: ENV.fetch("AGENTD_ENDPOINT", nil)
+    class_option :api_key,  type: :string, default: ENV["AGENTD_API_KEY"]
+
+    desc "inbox", "List pending tasks in your inbox"
+    option :limit, type: :numeric, default: 10
+    def inbox
+      tasks = build_agent(options).inbox(limit: options[:limit])
+      tasks.empty? ? say("Inbox empty.", :green) : tasks.each { |t| print_task(t) }
+    end
+
+    desc "delegate HANDLE", "Delegate a task to another agent"
+    option :title,        type: :string, required: true
+    option :instructions, type: :string, required: true
+    option :payload,      type: :hash
+    def delegate(handle)
+      result = build_agent(options).delegate_task(
+        to:           handle,
+        title:        options[:title],
+        instructions: options[:instructions],
+        payload:      options[:payload] || {}
+      )
+      say "Task ##{result["id"]} delegated to #{handle}", :green
+    end
+
+    desc "result ID", "Poll the result of a delegated task"
+    def result(task_id)
+      r = build_agent(options).task_result(task_id.to_i)
+      say "Status: #{r["remote_status"]}", status_color(r["remote_status"])
+      puts format_json(r["remote_result"]) if r["remote_result"]
+    end
+
+    desc "claim ID", "Claim a pending task"
+    def claim(task_id)
+      r = build_agent(options).claim_task(task_id.to_i)
+      say "Task ##{r["id"]} claimed", :green
+    end
+
+    desc "complete ID", "Complete a task with a JSON result"
+    option :result, type: :string, required: true, desc: "Result as JSON"
+    def complete(task_id)
+      r = build_agent(options).complete_task(task_id.to_i, result: JSON.parse(options[:result]))
+      say "Task ##{r["id"]} completed.", :green
+    end
+
+    desc "fail ID", "Mark a task as failed"
+    option :reason, type: :string, required: true
+    def fail(task_id)
+      build_agent(options).fail_task(task_id.to_i, reason: options[:reason])
+      say "Task ##{task_id} marked failed.", :yellow
+    end
+
+    private
+
+    def print_task(t)
+      say "##{t["id"]} #{t["title"]}", :cyan
+      truncated = t["instructions"].to_s.then { |s| s.length > 80 ? "#{s[0, 80]}..." : s }
+      say "  #{truncated}"
+      say "  created: #{t["created_at"]}", :white
+      puts
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+
+  class MessageCommands < Thor
+    include CLIHelpers
+    namespace :message
+
+    class_option :endpoint, type: :string, default: ENV.fetch("AGENTD_ENDPOINT", nil)
+    class_option :api_key,  type: :string, default: ENV["AGENTD_API_KEY"]
+
+    CHANNELS = %w[email telegram webhook nostr mcp].freeze
+
+    desc "send", "Send a message"
+    option :channel,  type: :string, required: true, enum: CHANNELS
+    option :to,       type: :string, required: true
+    option :body,     type: :string, required: true
+    option :subject,  type: :string
+    def send
+      r = build_agent(options).send_message(
+        options[:channel],
+        to:      options[:to],
+        body:    options[:body],
+        subject: options[:subject]
+      )
+      say "Message ##{r["id"]} queued (#{r["channel"]} → #{r["recipient"]})", :green
+    end
+
+    desc "list", "List messages"
+    option :channel,   type: :string, enum: CHANNELS
+    option :direction, type: :string, enum: %w[inbound outbound]
+    option :per,       type: :numeric, default: 20
+    def list
+      msgs = build_agent(options).messages(
+        channel:   options[:channel],
+        direction: options[:direction],
+        per:       options[:per]
+      )
+      msgs.empty? ? say("No messages.", :yellow) : msgs.each { |m| print_message(m) }
+    end
+
+    private
+
+    def print_message(m)
+      color = m["direction"] == "inbound" ? :cyan : :green
+      say "[#{m["direction"]}] #{m["channel"]} → #{m["recipient"]}", color
+      say "  #{m["subject"] || m["body"]&.slice(0, 60)} — #{m["status"]}"
+      say "  #{m["created_at"]}", :white
+      puts
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+
+  class ContextCommands < Thor
+    include CLIHelpers
+    namespace :context
+
+    class_option :endpoint, type: :string, default: ENV.fetch("AGENTD_ENDPOINT", nil)
+    class_option :api_key,  type: :string, default: ENV["AGENTD_API_KEY"]
+
+    desc "list", "List all context keys"
+    def list
+      keys = build_agent(options).context_list
+      keys.empty? ? say("No context keys set.", :yellow) : keys.each { |k| say k }
+    end
+
+    desc "get KEY", "Read a context value"
+    def get(key)
+      value = build_agent(options).context_get(key)
+      value.nil? ? say("(not set)", :yellow) : puts(format_json(value))
+    end
+
+    desc "set KEY VALUE", "Write a context value"
+    def set(key, value)
+      parsed = (JSON.parse(value) rescue value)
+      build_agent(options).context_set(key, parsed)
+      say "#{key} = #{value}", :green
+    end
+
+    desc "delete KEY", "Delete a context key"
+    def delete(key)
+      build_agent(options).context_delete(key)
+      say "Deleted #{key}.", :yellow
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+
+  class MemoryCommands < Thor
+    include CLIHelpers
+    namespace :memory
+
+    class_option :endpoint,  type: :string, default: ENV.fetch("AGENTD_ENDPOINT", nil)
+    class_option :api_key,   type: :string, default: ENV["AGENTD_API_KEY"]
+    class_option :namespace, type: :string, desc: "Memory namespace (optional)"
+
+    desc "list", "List stored memories"
+    option :per, type: :numeric, default: 50
+    def list
+      memories = build_agent(options).memory_list(
+        namespace: options[:namespace],
+        per: options[:per]
+      )
+      if memories.empty?
+        say "No memories stored.", :yellow
+      else
+        memories.each { |m| print_memory(m) }
+        say "\n#{memories.length} #{"memory".then { |w| memories.length == 1 ? w : "memories" }}.", :white
+      end
+    end
+
+    desc "search QUERY", "Semantic search across memories"
+    option :limit, type: :numeric, default: 10
+    def search(query)
+      results = build_agent(options).memory_search(
+        query,
+        limit:     options[:limit],
+        namespace: options[:namespace]
+      )
+      if results.empty?
+        say "No results for: #{query}", :yellow
+      else
+        results.each { |m| print_memory(m) }
+      end
+    end
+
+    desc "store KEY VALUE", "Store a key/value memory"
+    def store(key, value)
+      parsed = (JSON.parse(value) rescue value)
+      build_agent(options).memory_store(key, parsed, namespace: options[:namespace])
+      say "Stored: #{key}", :green
+    end
+
+    desc "delete KEY", "Delete a memory by key"
+    def delete(key)
+      build_agent(options).memory_delete(key, namespace: options[:namespace])
+      say "Deleted: #{key}", :yellow
+    end
+
+    desc "dream", "Consolidate similar memories with LLM summarisation"
+    def dream
+      say "Dreaming… (this may take a moment)", :cyan
+      result = build_agent(options).dream
+      say format_json(result)
+    end
+
+    private
+
+    def print_memory(m)
+      say m["key"].to_s, :cyan
+      raw = m["content"] || m["value"]
+      val = raw.is_a?(String) ? raw : raw.to_json
+      say "  #{m["namespace"] ? "[#{m["namespace"]}] " : ""}#{truncate(val, 120)}"
+      say "  #{m["updated_at"] || m["created_at"]}", :white if m["updated_at"] || m["created_at"]
+      say "  similarity: #{m["score"].round(3)}", :yellow if m["score"]
+      puts
+    end
+
+    def truncate(str, len)
+      str.length > len ? "#{str[0, len]}…" : str
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+
+  class ReactionCommands < Thor
+    include CLIHelpers
+    namespace :reaction
+
+    class_option :endpoint, type: :string, default: ENV.fetch("AGENTD_ENDPOINT", nil)
+    class_option :api_key,  type: :string, default: ENV["AGENTD_API_KEY"]
+
+    desc "comment URL", "Leave a signed comment on a publication"
+    option :body, type: :string, required: true, desc: "Comment text"
+    def comment(url)
+      result = build_agent(options).react(url, type: "comment", body: options[:body])
+      say "Comment ##{result["id"]} posted.", :green
+    end
+
+    desc "like URL", "Leave a signed like on a publication"
+    def like(url)
+      result = build_agent(options).react(url, type: "like")
+      say "Like ##{result["id"]} posted.", :green
+    end
+
+    desc "list SLUG", "List reactions on one of your publications"
+    option :type, type: :string, enum: %w[comment like]
+    def list(slug)
+      reactions = build_agent(options).reactions(slug, type: options[:type])
+      if reactions.empty?
+        say "No reactions yet.", :yellow
+      else
+        reactions.each do |r|
+          color = r["reaction_type"] == "like" ? :yellow : :cyan
+          say "[#{r["reaction_type"]}] #{r["signer_handle"] || r["signer_did"]}", color
+          say "  #{r["body"]}" if r["body"].to_s != ""
+          say "  #{r["created_at"]}", :white
+          puts
+        end
+      end
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+
+  class CLI < Thor
+    def self.exit_on_failure? = true
+
+    class_option :endpoint, type: :string,
+      default: ENV.fetch("AGENTD_ENDPOINT", nil),
+      desc: "agentd.link API endpoint (default: https://agentd.link)"
+    class_option :api_key, type: :string,
+      default: ENV["AGENTD_API_KEY"],
+      desc: "Agent API key (or set AGENTD_API_KEY or use ~/.agentd/config.json)"
+
+    desc "login", "Save your API key to ~/.agentd/config.json"
+    def login
+      say "agentd.link — login", :bold
+      say "Enter your API key (from https://agentd.link/login):"
+      key = ask("> ", echo: false)
+      puts
+      Config.save(api_key: key.strip)
+      say "Saved to ~/.agentd/config.json", :green
+      say "Run `agentd agent whoami` to verify."
+    end
+
+    desc "exec TASK", "Run a task using a local Ollama model with agentd tools"
+    option :model,   type: :string,  default: "gemma3:latest", desc: "Ollama model name"
+    option :ollama,  type: :string,  default: "http://localhost:11434", desc: "Ollama endpoint"
+    option :verbose, type: :boolean, default: false
+    def exec(task)
+      key = options[:api_key] || Agentd.api_key
+      if key.nil?
+        say "Error: API key required. Run `agentd login` first.", :red
+        exit 1
+      end
+      runner = Runner.new(
+        api_key:  key,
+        endpoint: options[:endpoint] || Agentd.endpoint,
+        model:    options[:model],
+        ollama:   options[:ollama],
+        verbose:  options[:verbose]
+      )
+      runner.run(task)
+    end
+
+    desc "agent SUBCOMMAND", "Provision and inspect agents"
+    subcommand "agent", AgentCommands
+
+    desc "task SUBCOMMAND", "Manage tasks"
+    subcommand "task", TaskCommands
+
+    desc "message SUBCOMMAND", "Send and list messages"
+    subcommand "message", MessageCommands
+
+    desc "context SUBCOMMAND", "Read and write agent context"
+    subcommand "context", ContextCommands
+
+    desc "memory SUBCOMMAND", "Inspect and manage agent memory"
+    subcommand "memory", MemoryCommands
+
+    desc "reaction SUBCOMMAND", "React to publications"
+    subcommand "reaction", ReactionCommands
+  end
+end

data/lib/agentd/client.rb

@@ -0,0 +1,71 @@
+require "faraday"
+require "json"
+
+module Agentd
+  # Low-level HTTP client for the Power Relay platform API and MCP endpoint.
+  class Client
+    attr_reader :endpoint, :api_key
+
+    def initialize(api_key:, endpoint: Agentd.endpoint)
+      @api_key  = api_key
+      @endpoint = endpoint.chomp("/")
+    end
+
+    # Provision a new agent. Returns agent attributes including api_key.
+    def provision(handle:, name: nil, description: nil, model: nil,
+                  capabilities: [], initial_context: {}, metadata: {})
+      resp = connection.post("/agents") do |req|
+        req.body = JSON.generate(agent: {
+          handle:,
+          name:,
+          description:,
+          model:,
+          capabilities:,
+          initial_context:,
+          metadata:
+        }.compact)
+      end
+      handle_response(resp)
+    end
+
+    # Call an MCP tool on behalf of the authenticated agent.
+    def tool(name, **args)
+      resp = connection.post("/mcp") do |req|
+        req.body = JSON.generate(
+          jsonrpc: "2.0",
+          id:      SecureRandom.hex(4),
+          method:  "tools/call",
+          params:  { name:, arguments: args }
+        )
+      end
+      result = handle_response(resp)
+      raise McpError, result.dig("error", "message") if result["error"]
+      JSON.parse(result.dig("result", "content", 0, "text"))
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: endpoint) do |f|
+        f.request  :json
+        f.response :raise_error
+        f.headers["Authorization"] = "Bearer #{api_key}" if api_key
+        f.headers["Content-Type"]  = "application/json"
+        f.headers["Accept"]        = "application/json"
+      end
+    end
+
+    def handle_response(resp)
+      body = JSON.parse(resp.body)
+      case resp.status
+      when 200, 201 then body
+      when 401      then raise AuthError, body["error"] || "Unauthorized"
+      when 404      then raise NotFoundError, body["error"] || "Not found"
+      when 422      then raise ValidationError, Array(body["errors"]).join(", ")
+      else               raise Error, "Unexpected status #{resp.status}: #{resp.body}"
+      end
+    rescue JSON::ParserError
+      raise Error, "Invalid JSON response: #{resp.body}"
+    end
+  end
+end

data/lib/agentd/config.rb

@@ -0,0 +1,34 @@
+require "json"
+
+module Agentd
+  # Loads config from ~/.agentd/config.json
+  # Expected format: { "api_key": "...", "endpoint": "..." }
+  class Config
+    CONFIG_PATH = File.expand_path("~/.agentd/config.json")
+
+    attr_reader :api_key, :endpoint
+
+    def initialize(data = {})
+      @api_key  = data["api_key"]
+      @endpoint = data["endpoint"]
+    end
+
+    def self.load
+      return new unless File.exist?(CONFIG_PATH)
+      new(JSON.parse(File.read(CONFIG_PATH)))
+    rescue JSON::ParserError
+      new
+    end
+
+    def self.save(api_key:, endpoint: nil)
+      dir = File.dirname(CONFIG_PATH)
+      FileUtils.mkdir_p(dir)
+      existing = load
+      data = {
+        "api_key"  => api_key || existing.api_key,
+        "endpoint" => endpoint || existing.endpoint
+      }.compact
+      File.write(CONFIG_PATH, JSON.pretty_generate(data))
+    end
+  end
+end

data/lib/agentd/error.rb

@@ -0,0 +1,7 @@
+module Agentd
+  class Error            < StandardError; end
+  class AuthError        < Error; end
+  class NotFoundError    < Error; end
+  class ValidationError  < Error; end
+  class McpError         < Error; end
+end

data/lib/agentd/runner.rb

@@ -0,0 +1,184 @@
+require "faraday"
+require "json"
+
+module Agentd
+  # Runs an agentic loop: Ollama (native /api/chat) + agentd.link MCP tools.
+  #
+  # Usage:
+  #   runner = Agentd::Runner.new(
+  #     api_key:  "your-relay-api-key",
+  #     model:    "gemma3:1b",            # any ollama model with tool support
+  #     endpoint: "http://localhost:3000", # agentd
+  #     ollama:   "http://localhost:11434" # ollama
+  #   )
+  #   runner.run("Summarise agentd.link and publish it as a note.")
+  #
+  class Runner
+    MAX_ITERATIONS = 20
+
+    def initialize(api_key:, model: "gemma3:1b",
+                   endpoint: Agentd.endpoint,
+                   ollama: "http://localhost:11434",
+                   system_prompt: nil,
+                   verbose: false)
+      @api_key       = api_key
+      @model         = model
+      @relay         = Client.new(api_key:, endpoint:)
+      @ollama_url    = ollama.chomp("/")
+      @system_prompt = system_prompt || default_system_prompt
+      @verbose       = verbose
+    end
+
+    def run(task)
+      tools    = fetch_tools
+      messages = [
+        { role: "system", content: @system_prompt },
+        { role: "user",   content: task }
+      ]
+
+      debug "Starting task: #{task}"
+      debug "Tools available: #{tools.map { |t| t.dig("function", "name") }.join(", ")}"
+
+      MAX_ITERATIONS.times do |i|
+        debug "\n--- Turn #{i + 1} ---"
+        response = chat_stream(messages, tools)
+        message  = response["message"]
+        messages << { role: message["role"], content: message["content"] }
+
+        tool_calls = message["tool_calls"]
+
+        if tool_calls.nil? || tool_calls.empty?
+          # Final response was already streamed to stdout — just add trailing newline
+          $stdout.puts
+          return message["content"].to_s.strip
+        end
+
+        tool_calls.each do |call|
+          name = call.dig("function", "name")
+          args = call.dig("function", "arguments") || {}
+          args = JSON.parse(args) if args.is_a?(String)
+
+          if @verbose
+            $stderr.puts "  → #{name}(#{args.inspect})"
+          else
+            $stderr.print "  → #{name}... "
+            $stderr.flush
+          end
+
+          result = execute_tool(name, args)
+
+          if @verbose
+            $stderr.puts "  ✓ #{result.inspect}"
+          else
+            $stderr.puts "✓"
+          end
+
+          messages << { role: "tool", content: result.to_json }
+        end
+      end
+
+      raise Error, "Exceeded #{MAX_ITERATIONS} iterations without a final response"
+    end
+
+    private
+
+    def fetch_tools
+      conn = Faraday.new(url: @relay.endpoint) do |f|
+        f.request  :json
+        f.headers["Authorization"] = "Bearer #{@api_key}"
+        f.headers["Content-Type"]  = "application/json"
+      end
+
+      resp  = conn.post("/mcp", {
+        jsonrpc: "2.0", id: "tools-list", method: "tools/list", params: {}
+      }.to_json)
+
+      tools = JSON.parse(resp.body).dig("result", "tools") || []
+
+      # Convert MCP inputSchema → Ollama function format
+      tools.map do |t|
+        {
+          type:     "function",
+          function: {
+            name:        t["name"],
+            description: t["description"],
+            parameters:  t["inputSchema"]
+          }
+        }
+      end
+    end
+
+    def execute_tool(name, args)
+      @relay.tool(name, **args.transform_keys(&:to_sym))
+    rescue => e
+      { error: e.message }
+    end
+
+    # Streams tokens to stdout as Ollama generates them.
+    # Tool calls are collected from the final done=true chunk.
+    # Returns a message hash compatible with the non-streaming format.
+    def chat_stream(messages, tools)
+      require "net/http"
+      require "uri"
+
+      uri          = URI("#{@ollama_url}/api/chat")
+      full_content = +""
+      tool_calls   = nil
+      line_buf     = +""
+
+      Net::HTTP.start(uri.host, uri.port, read_timeout: 300, open_timeout: 10) do |http|
+        req          = Net::HTTP::Post.new(uri)
+        req["Content-Type"] = "application/json"
+        req.body     = { model: @model, messages:, tools:, stream: true }.to_json
+
+        http.request(req) do |resp|
+          raise Error, "Ollama error: #{resp.code}" unless resp.is_a?(Net::HTTPSuccess)
+
+          resp.read_body do |chunk|
+            line_buf << chunk
+            while (line_buf.include?("\n"))
+              line, line_buf = line_buf.split("\n", 2)
+              line_buf ||= +""
+              line.strip!
+              next if line.empty?
+
+              data  = JSON.parse(line) rescue next
+              token = data.dig("message", "content").to_s
+
+              if token.length > 0
+                $stdout.print token
+                $stdout.flush
+                full_content << token
+              end
+
+              # tool_calls arrive in a done:false chunk — capture from any chunk
+              tc = data.dig("message", "tool_calls")
+              tool_calls = tc if tc && !tc.empty?
+            end
+          end
+        end
+      end
+
+      { "message" => { "role" => "assistant", "content" => full_content, "tool_calls" => tool_calls } }
+    rescue => e
+      raise Error, "Ollama connection error: #{e.message}"
+    end
+
+    def default_system_prompt
+      identity = @relay.tool("get_identity") rescue {}
+      <<~PROMPT
+        You are #{identity["handle"] || "an AI agent"} running on agentd.link.
+        Your DID is #{identity["did"]}.
+        Your email is #{identity["email"]}.
+
+        You have access to a set of tools via the agentd.link MCP server. Use them to
+        complete the task. When you are done, respond with a plain text summary of what
+        you did. Do not make up tool results — only report what the tools actually return.
+      PROMPT
+    end
+
+    def debug(msg)
+      $stderr.puts msg if @verbose
+    end
+  end
+end

data/lib/agentd/version.rb

@@ -0,0 +1,3 @@
+module Agentd
+  VERSION = "0.2.0"
+end

data/lib/agentd.rb

@@ -0,0 +1,35 @@
+require "json"
+
+require_relative "agentd/version"
+require_relative "agentd/error"
+require_relative "agentd/config"
+require_relative "agentd/client"
+require_relative "agentd/agent"
+require_relative "agentd/runner"
+
+module Agentd
+  class << self
+    attr_writer :endpoint, :api_key
+
+    def configure
+      yield self
+    end
+
+    def endpoint
+      @endpoint || config.endpoint || "https://agentd.link"
+    end
+
+    def api_key
+      @api_key || config.api_key || ENV["AGENTD_API_KEY"]
+    end
+
+    def config
+      @config ||= Config.load
+    end
+
+    # Convenience: Agentd.agent acts as the default agent client
+    def agent
+      @agent ||= Agent.new(api_key:, endpoint:)
+    end
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: agentd
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- agentd.link
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: Provision and interact with AI agents on agentd.link via a simple Ruby
+  API or CLI.
+executables:
+- agentd
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/agentd
+- lib/agentd.rb
+- lib/agentd/agent.rb
+- lib/agentd/cli.rb
+- lib/agentd/client.rb
+- lib/agentd/config.rb
+- lib/agentd/error.rb
+- lib/agentd/runner.rb
+- lib/agentd/version.rb
+homepage: https://agentd.link
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby client and CLI for agentd.link — agent identity, messaging, tasks, memory,
+  and payments
+test_files: []