ctxmesh 0.0.1.pre → 0.1.0.pre.beta.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95d2cc68599cb93ce35ccc3d92d5724c7e2e741b701416f4011c76386af63cb1
-  data.tar.gz: 97e316d31984b7cff9ce4cb62be2e7ae39321a407d4368e60f4aa542fed338b7
+  metadata.gz: ce25dc8c1240107783738a291b4288ceb2dc75420130bfff83d42613af875838
+  data.tar.gz: edbf4b51e49bcd272cde852c9ae84654d09d7b416925cdbe35ab4f835f0a7f31
 SHA512:
-  metadata.gz: e8da9df2e5ec8633dff60acdb23ac254343bba2492e280d0e260e3e975c874d031330167799ea3f3d738e43c96ed3cef013b35d8e3a55143c6ce9c0c681ce442
-  data.tar.gz: b4cd9f4202a4247f6b818a5bd469fbbd448f012452fc5c62b70ca774cd6e427caf9feed2858e0a8b3c5d2f2facc2678af724a680e1ac7a033fca360fe1677445
+  metadata.gz: d7c147f0e15b649eedb21b2beb00eb17cafb4f2d6b68884733765c48ffd382225f650b6590a0c19b90911b4a3519734c24d6f4c4441ed481a7b23311714efb4b
+  data.tar.gz: 06c25966b09429cc589a27a56d95538ee52780ef9e42f134c2b0932cd5154f9e686112fa910d55411cadee945bf493e45325804af177d8973e02c17a4e5eb18f

data/README.md

@@ -1,11 +1,55 @@
-# ctxmesh (Ruby)
+# ctxmesh — Ruby SDK
 
-**Pre-release.** This gem reserves the `ctxmesh` name for the official Ruby SDK, published by the
-ctxmesh project. **It has no functionality yet.**
+Typed clients for agents running on [ctxmesh](https://ctxmesh.github.io), the Kubernetes-native
+control plane for AI agents.
 
-Working SDKs today:
+Your agent runs in a pod beside the platform's sidecars. This gem is the typed way to reach
+them — conversation memory, long-term memory, knowledge bases, skills, feedback, agent-to-agent
+calls, delegation and handoff.
 
-- **Python** — `pip install ctxmesh`
-- **TypeScript** — `npm install ctxmesh`
+**Your code never holds credentials.** Endpoints and identity arrive in the environment the
+platform injects, so there is no API key to manage and no base URL to configure.
 
-Source and issues: https://github.com/ctxmesh/ctxmesh
+```ruby
+gem "ctxmesh"
+```
+
+## Use it
+
+```ruby
+require "ctxmesh"
+
+cx = Ctxmesh::Client.from_env      # reads MEMORY_PORT, CONVERSATION_ID, …
+
+cx.memory_append(role: "user", content: "What changed in the deploy?")
+history = cx.memory_get
+
+cx.remember("The customer prefers email.", { "topic" => "prefs" })
+facts = cx.search_agent("contact preference", top_k: 5)
+
+hits = cx.knowledge_search("rollback procedure", top_k: 5)
+cx.feedback(trace_id, "helpfulness", 1.0, "clear")
+```
+
+`Ctxmesh::Client.from_env` raises `NotInPodError` outside the platform.
+
+## Errors say which kind of "no" it was
+
+- **`NotWiredError`** — the platform did not grant this capability. The port is absent because
+  nothing is listening; a configuration answer, not a failure.
+- **`DeniedError`** — a 403. The plane understood the call and refused it (a guardrail, a
+  budget, the delegate fence), and it carries the reason.
+- **`ApiError`** — any other non-2xx, with the body.
+
+## No runtime dependencies
+
+`net/http` and the stdlib `json`. A gem dependency in an SDK becomes a version conflict in every
+application that already has it.
+
+## Conformance tier
+
+**plane-client** — every launcher route is reachable here. The managed agent loop and
+model client are authoring-tier and live in the Python and TypeScript SDKs. Every capability is
+also a plain HTTP endpoint, so this gem is convenience, never a requirement.
+
+Apache-2.0.

data/lib/ctxmesh/config.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Ctxmesh
+  # The resolved plane for one agent process.
+  class Config
+    DEFAULT_MEMORY_PORT = 2998
+    DEFAULT_FEEDBACK_PORT = 2995
+    DEFAULT_AMP_PORT = 2997
+    DEFAULT_DELEGATE_PORT = 2994
+
+    attr_reader :memory_port, :feedback_port, :amp_port, :delegate_port, :agent_name, :conversation_id
+
+    def initialize(memory_port:, feedback_port:, amp_port:, delegate_port: DEFAULT_DELEGATE_PORT,
+                   agent_name: "", conversation_id: "",
+                   memory_wired: true, feedback_wired: true, long_term_enabled: true,
+                   knowledge_enabled: true)
+      @memory_port = memory_port
+      @feedback_port = feedback_port
+      @amp_port = amp_port
+      @delegate_port = delegate_port
+      @agent_name = agent_name
+      @conversation_id = conversation_id
+      @memory_wired = memory_wired
+      @feedback_wired = feedback_wired
+      @long_term_enabled = long_term_enabled
+      @knowledge_enabled = knowledge_enabled
+    end
+
+    # False when MEMORY_PORT was absent: the platform did not grant memory to this agent.
+    def memory_wired? = @memory_wired
+    def feedback_wired? = @feedback_wired
+    def long_term_enabled? = @long_term_enabled
+    def knowledge_enabled? = @knowledge_enabled
+
+    def memory_base = "http://127.0.0.1:#{@memory_port}"
+    def feedback_base = "http://127.0.0.1:#{@feedback_port}"
+    def amp_base = "http://127.0.0.1:#{@amp_port}"
+    # Its OWN listener. /delegate and /handoff on the memory port are a 404.
+    def delegate_base = "http://127.0.0.1:#{@delegate_port}"
+
+    # Reads the launcher environment.
+    def self.from_env(env = ENV)
+      in_pod = %w[MEMORY_PORT FEEDBACK_PORT AGENT_NAME MODEL_GATEWAY_URL].any? { |k| env.key?(k) }
+      raise NotInPodError, "ctxmesh: not running in a ctxmesh pod (no launcher environment)" unless in_pod
+
+      mem, mem_set = port(env, "MEMORY_PORT", DEFAULT_MEMORY_PORT)
+      fb, fb_set = port(env, "FEEDBACK_PORT", DEFAULT_FEEDBACK_PORT)
+      # A2A_PORT is what the launcher publishes; AMP_PORT was invented.
+      amp, = port(env, "A2A_PORT", DEFAULT_AMP_PORT)
+      del, = port(env, "DELEGATE_PORT", DEFAULT_DELEGATE_PORT)
+
+      new(
+        memory_port: mem, feedback_port: fb, amp_port: amp, delegate_port: del,
+        agent_name: env.fetch("AGENT_NAME", "").strip,
+        conversation_id: env.fetch("CONVERSATION_ID", "").strip,
+        memory_wired: mem_set, feedback_wired: fb_set,
+        long_term_enabled: env.fetch("MEMORY_LONGTERM_ENABLED", "").strip == "true",
+        knowledge_enabled: env.fetch("KNOWLEDGE_BASE_ENABLED", "").strip == "true"
+      )
+    end
+
+    # Returns [value, was_explicitly_set]. The caller needs the difference: an unset port means
+    # the capability is not wired, not that it is on the default.
+    def self.port(env, name, default)
+      raw = env[name]
+      return [default, false] if raw.nil? || raw.strip.empty?
+
+      n = Integer(raw.strip, exception: false)
+      unless n && n.between?(1, 65_535)
+        raise NotInPodError, "ctxmesh: #{name}=#{raw.inspect} is not a valid port"
+      end
+
+      [n, true]
+    end
+    private_class_method :port
+  end
+end

data/lib/ctxmesh/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ctxmesh
+  # Base for everything this SDK raises.
+  class Error < StandardError; end
+
+  # The launcher environment is absent: this process is not running as a ctxmesh agent.
+  # Raised rather than guessing ports, so running an agent on a laptop says so plainly instead
+  # of failing later with a connection refused to localhost:2998.
+  class NotInPodError < Error; end
+
+  # The platform did not grant this capability to this agent. A configuration answer, not a
+  # failure: the port is absent because nothing is listening.
+  class NotWiredError < Error; end
+
+  # A non-2xx response from the plane.
+  class ApiError < Error
+    attr_reader :status, :path, :body
+
+    def initialize(status, path, body)
+      @status = status
+      @path = path
+      @body = body
+      super("ctxmesh: #{path} returned #{status}: #{body}")
+    end
+  end
+
+  # A 403 — the plane understood the call and refused it. Guardrails, budgets and the delegate
+  # fence surface here, and the reason survives: a refusal that says only "403" turns a policy
+  # decision into a bare status code.
+  class DeniedError < ApiError
+    def initialize(path, body)
+      super(403, path, body)
+    end
+  end
+end

data/lib/ctxmesh/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Ctxmesh
+  # Stamped from the product tag at release (ADR 0135). Every SDK ships at one version.
+  VERSION = "0.1.0-beta.3"
+end

data/lib/ctxmesh.rb

@@ -1,9 +1,265 @@
 # frozen_string_literal: true
 
-# Ctxmesh is the official Ruby namespace for ctxmesh.
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "ctxmesh/version"
+require_relative "ctxmesh/errors"
+require_relative "ctxmesh/config"
+
+# Ruby SDK for agents running on ctxmesh, the Kubernetes-native control plane for AI agents.
+#
+# An agent runs in a pod beside the platform's sidecars, and this gem is the typed way to reach
+# them over localhost: conversation memory, long-term memory, knowledge bases, skills, feedback,
+# agent-to-agent calls, delegation and handoff.
 #
-# The Ruby SDK is not implemented yet. Python and TypeScript SDKs are
-# available today; see https://github.com/ctxmesh/ctxmesh.
+# It holds no credentials. Endpoints and identity arrive in the environment the platform
+# injects, so there is no API key to manage and no base URL to configure.
+#
+# Conformance tier: plane-client (ADR 0139). The managed agent loop and model client are
+# authoring-tier and live in the Python and TypeScript SDKs.
 module Ctxmesh
-  VERSION = "0.0.1.pre"
+  # Carries the run capability. Delegation, handoff, per-user session memory, per-user long-term
+  # memory and per-user knowledge bases all key on it. Session memory fails SAFE without it --
+  # every user silently shares the agent-wide bucket instead of their own -- so omitting it
+  # defeats an isolation control with no error to notice.
+  CAPABILITY_HEADER = "X-Ctxmesh-Run-Capability"
+
+  # The entry point.
+  class Client
+    DEFAULT_TIMEOUT = 15
+    # Search may wait on an embedding call through the token-service.
+    SEARCH_TIMEOUT = 60
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    # Reads the launcher environment. Raises NotInPodError outside a ctxmesh pod.
+    def self.from_env(env = ENV) = new(Config.from_env(env))
+
+    # Builds a client from an explicit config — for tests and offline work.
+    def self.from_config(config) = new(config)
+
+    # ── memory: /memory and /memory/agent ───────────────────────────────────
+
+    # Returns the conversation so far.
+    def memory_get(conversation_id = nil)
+      require_memory!
+      body = request("GET", "#{@config.memory_base}/memory/#{escape(conv(conversation_id))}")
+      body.is_a?(Array) ? body : []
+    end
+
+    # Adds one entry to the conversation.
+    def memory_append(role:, content:, conversation_id: nil)
+      require_memory!
+      request("POST", "#{@config.memory_base}/memory/#{escape(conv(conversation_id))}/append",
+              { role: role, content: content })
+      nil
+    end
+
+    # Searches this conversation's memory. capability is optional: without it a per-user agent
+    # silently reads the agent-wide bucket rather than the caller's own.
+    def memory_search(query, conversation_id: nil, capability: nil)
+      require_memory!
+      url = "#{@config.memory_base}/memory/#{escape(conv(conversation_id))}/search?q=#{escape(query.to_s)}"
+      headers = capability && !capability.empty? ? { CAPABILITY_HEADER => capability } : {}
+      body = request("GET", url, nil, DEFAULT_TIMEOUT, headers)
+      body.is_a?(Array) ? body : []
+    end
+
+    # Replaces the conversation wholesale.
+    def memory_put(entries, conversation_id: nil)
+      require_memory!
+      request("PUT", "#{@config.memory_base}/memory/#{escape(conv(conversation_id))}", entries)
+      nil
+    end
+
+    # Writes a fact to this agent's long-term memory.
+    def remember(content, tags = {})
+      require_long_term!
+      payload = { content: content }
+      payload[:tags] = tags unless tags.nil? || tags.empty?
+      request("POST", "#{@config.memory_base}/memory/agent/remember", payload)
+      nil
+    end
+
+    # Retrieves facts from long-term memory; min_score drops weak matches.
+    def search_agent(query, top_k: 5, min_score: 0.0)
+      require_long_term!
+      body = request("POST", "#{@config.memory_base}/memory/agent/search",
+                     { query: query, topK: top_k.positive? ? top_k : 5 })
+      results(body).select { |f| f.fetch("score", 0.0) >= min_score }
+    end
+
+    # ── knowledge: /knowledge/search ────────────────────────────────────────
+
+    # Retrieval over the granted knowledge bases; knowledge_base may be nil for all of them.
+    def knowledge_search(query, knowledge_base: nil, top_k: 5)
+      unless @config.knowledge_enabled?
+        raise NotWiredError, "ctxmesh: knowledge is not enabled (KNOWLEDGE_BASE_ENABLED)"
+      end
+
+      if knowledge_base.nil? || knowledge_base.strip.empty?
+        raise Error, "ctxmesh: knowledgeBase is required (the launcher 400s without it)"
+      end
+
+      payload = { query: query, topK: top_k.positive? ? top_k : 5, knowledgeBase: knowledge_base }
+      results(request("POST", "#{@config.memory_base}/knowledge/search", payload, SEARCH_TIMEOUT))
+    end
+
+    # ── skills: /skills and /skills/load ────────────────────────────────────
+
+    # The skills the platform attached to this agent.
+    def skills
+      body = request("GET", "#{@config.memory_base}/skills")
+      body.is_a?(Hash) ? body.fetch("skills", []) : []
+    end
+
+    # Fetches a skill's body by name.
+    def skill_load(name)
+      body = request("POST", "#{@config.memory_base}/skills/load", { name: name })
+      # The launcher answers {"body": "..."}. Reading "content" gave "" with NO error,
+      # so a skill loaded as nothing and the model carried on without it.
+      body.is_a?(Hash) ? body.fetch("body", "") : ""
+    end
+
+    # ── feedback: /feedback ─────────────────────────────────────────────────
+
+    # Records a score against a trace — the signal that drives evals and canary promotion.
+    def feedback(trace_id, dimension, score, comment = nil)
+      unless @config.feedback_wired?
+        raise NotWiredError, "ctxmesh: feedback is not wired (FEEDBACK_PORT unset)"
+      end
+
+      # name/value, not dimension/score: the wrong keys returned 202 while writing a
+      # nameless zero score, silently corrupting the eval signal.
+      payload = { traceId: trace_id, name: dimension, value: score }
+      payload[:comment] = comment if comment && !comment.empty?
+      request("POST", "#{@config.feedback_base}/feedback", payload)
+      nil
+    end
+
+    # ── mesh: /amp and /a2a ─────────────────────────────────────────────────
+
+    # Invokes another agent through AMP.
+    def call_agent(target_agent, payload)
+      require_target!(target_agent)
+      request("POST", "#{@config.amp_base}/amp/#{escape(target_agent)}", payload)
+    end
+
+    # Invokes another agent through the retired /a2a path. Prefer #call_agent.
+    #
+    # Kept because the launcher still serves it (ADR 0138); an SDK that pretends a served route
+    # does not exist is the drift the contract gate exists to prevent.
+    def call_agent_legacy(target_agent, payload)
+      require_target!(target_agent)
+      request("POST", "#{@config.amp_base}/a2a/#{escape(target_agent)}", payload)
+    end
+
+    # ── runs: /delegate and /handoff ────────────────────────────────────────
+
+    # Spawns a sub-run on another agent.
+    #
+    # step and call_id are the idempotency key the launcher hard-requires -- the supervisor's loop
+    # iteration and the model's tool-call id -- so a reclaimed supervisor resolves to the SAME
+    # sub-run rather than spawning a second. capability is the run capability.
+    #
+    # The launcher answers 200 for EVERY outcome and signals success in "ok", so check that: a
+    # refusal decoded as a transport success is silent data loss, and "answer" is the entire point.
+    def delegate(sub_agent, step:, call_id:, capability:, input: nil)
+      raise Error, "ctxmesh: sub-agent is required" if sub_agent.nil? || sub_agent.strip.empty?
+      if step.to_s.strip.empty? || call_id.to_s.strip.empty?
+        raise Error, "ctxmesh: step and callId are required (the idempotency key)"
+      end
+      if capability.to_s.strip.empty?
+        raise NotWiredError, "ctxmesh: delegation needs the run capability (#{CAPABILITY_HEADER})"
+      end
+
+      request("POST", "#{@config.delegate_base}/delegate",
+              { subAgent: sub_agent, input: input, step: step, callId: call_id },
+              DEFAULT_TIMEOUT, { CAPABILITY_HEADER => capability }) || {}
+    end
+
+    # Transfers the conversation to another agent.
+    #
+    # The launcher treats an ABSENT includeHistory as TRUE, so it is always sent explicitly --
+    # defaulting to false handed the receiver nothing. message is its opening note.
+    def handoff(target_agent, capability:, message: nil, include_history: true)
+      require_target!(target_agent)
+      if capability.to_s.strip.empty?
+        raise NotWiredError, "ctxmesh: handoff needs the run capability (#{CAPABILITY_HEADER})"
+      end
+
+      payload = { targetAgent: target_agent, includeHistory: include_history }
+      payload[:message] = message if message && !message.empty?
+      request("POST", "#{@config.delegate_base}/handoff", payload,
+              DEFAULT_TIMEOUT, { CAPABILITY_HEADER => capability }) || {}
+    end
+
+    private
+
+    def require_memory!
+      return if @config.memory_wired?
+
+      raise NotWiredError, "ctxmesh: memory is not wired (MEMORY_PORT unset)"
+    end
+
+    def require_long_term!
+      require_memory!
+      return if @config.long_term_enabled?
+
+      raise NotWiredError, "ctxmesh: long-term memory is not enabled (MEMORY_LONGTERM_ENABLED)"
+    end
+
+    def require_target!(t)
+      raise Error, "ctxmesh: target agent is required" if t.nil? || t.strip.empty?
+    end
+
+    # Explicit id first, else the injected CONVERSATION_ID. Empty is an error rather than a
+    # silent write to a shared bucket.
+    def conv(id)
+      v = id.nil? || id.to_s.strip.empty? ? @config.conversation_id : id.to_s
+      raise Error, "ctxmesh: no conversation id (pass one, or set CONVERSATION_ID)" if v.strip.empty?
+      if v.include?("/") || v.match?(/\s/)
+        raise Error, "ctxmesh: conversation id #{v.inspect} contains a separator or whitespace"
+      end
+
+      v
+    end
+
+    def results(body) = body.is_a?(Hash) ? body.fetch("results", []) : []
+
+    def escape(s) = URI.encode_www_form_component(s)
+
+    def request(method, url, payload = nil, timeout = DEFAULT_TIMEOUT, headers = {})
+      uri = URI.parse(url)
+      req = Net::HTTP.const_get(method.capitalize).new(uri)
+      req["Accept"] = "application/json"
+      headers.each { |k, v| req[k] = v if v && !v.to_s.empty? }
+      if payload
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(payload)
+      end
+
+      resp = Net::HTTP.start(uri.hostname, uri.port, open_timeout: 5, read_timeout: timeout) do |http|
+        http.request(req)
+      end
+
+      code = resp.code.to_i
+      text = (resp.body || "").strip
+      raise DeniedError.new(uri.path, text) if code == 403
+      raise ApiError.new(code, uri.path, text) unless (200..299).cover?(code)
+      return nil if text.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError => e
+      raise Error, "ctxmesh: decode response from #{uri.path}: #{e.message}"
+    rescue SystemCallError, Timeout::Error, IOError => e
+      raise Error, "ctxmesh: #{uri.path}: #{e.message}"
+    end
+  end
 end

metadata

@@ -1,33 +1,39 @@
 --- !ruby/object:Gem::Specification
 name: ctxmesh
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre
+  version: 0.1.0.pre.beta.3
 platform: ruby
 authors:
 - ctxmesh
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies: []
-description: Reserves the ctxmesh name for the official Ruby SDK. No functionality
-  yet; the Python and TypeScript SDKs are available today. See https://github.com/ctxmesh/ctxmesh.
-email: 
+description: 'Typed clients for agents running on ctxmesh: conversation memory, long-term
+  memory, knowledge bases, skills, feedback and agent-to-agent calls. Reads its endpoints
+  from the environment the platform injects, so your code never holds credentials.'
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - README.md
 - lib/ctxmesh.rb
-homepage: https://github.com/ctxmesh/ctxmesh
+- lib/ctxmesh/config.rb
+- lib/ctxmesh/errors.rb
+- lib/ctxmesh/version.rb
+homepage: https://ctxmesh.github.io
 licenses:
 - Apache-2.0
 metadata:
+  homepage_uri: https://ctxmesh.github.io
   source_code_uri: https://github.com/ctxmesh/ctxmesh
   bug_tracker_uri: https://github.com/ctxmesh/ctxmesh/issues
-  homepage_uri: https://github.com/ctxmesh/ctxmesh
+  documentation_uri: https://ctxmesh.github.io/sdk/
+  changelog_uri: https://github.com/ctxmesh/ctxmesh/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -38,12 +44,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: Official Ruby namespace for ctxmesh
+summary: Ruby SDK for ctxmesh agents
 test_files: []