asterism 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c3c929e3018c538fab3983c9fffce4fd997bfa8b37cad43fbaa6c0eb5890d65
-  data.tar.gz: b4fc43d2d5d286139eb700c5711786827aab41aa8a7628686b45270a321f1807
+  metadata.gz: a3f9045afdf176405f969bbf97ec703a00f6dc97b777224dfe71d449ebfcda29
+  data.tar.gz: '0748cc260662719332fa6a17030577ceb55ca53d137a9723ad100214c0518d72'
 SHA512:
-  metadata.gz: f971a84780f4a1ce1e24554530201f6bccaba7f8de6ec03c5b2dc6742c6c370e2567af5c82e4609fd82f582d32cbe314f82bc5c60d5815b5c33e805980b14a58
-  data.tar.gz: c355695ad9b52f7513f791191eeae8ded62011cdc011c50d1e921f6fa1e58190f491cc3adc0b367fa0087def3cfd6cd03729a43143b19f608b3f3a5603879f3c
+  metadata.gz: afc211c874d21e5d73bbb94d0e5bd870bd8aa3d840ccd57f7aaf072d9ecebb0bae72abd7a9d3e9fdb742498cbb3eb3220fa0a35fd213a9ce727f1e65ca8b738c
+  data.tar.gz: e12f369efedb87918e86d1eb70346e0da7404d08f5b9fdb37b8ce244be3bc90c85cabf9e9d548a928ad48f683e26574a5062eaf55cba9167361cbe05735301ab

data/CHANGELOG.md

@@ -6,6 +6,39 @@ the earlier ones are only in this repository. From 0.4.0 the two Zenoh
 bindings (asterism-zenoh, picoruby-asterism-zenoh) carry the same minor
 version (a patch release of one may come without the other).
 
+## Unreleased
+
+## 0.11.0
+
+- Needs CRuby 3.4 or newer (`required_ruby_version >= 3.4`; 3.2 is past its end of life). CI runs Ruby 3.4 and 4.0.
+
+## 0.10.0
+
+The command line and its MCP bridge only; the library and the wire are as
+in 0.9.0.
+
+- `asterism mcp` has a tool `asterism_values`: the latest value of each
+  key the applications put on (`asterism/<node>/<app>/<object>/<more>`,
+  e.g. a game table's state), as the server received them since it
+  started (it subscribes to `asterism/**` from the start). Arguments
+  `pattern` (`*`, `**`; default every key) and `wait` (seconds, at most
+  30: for the first put that matches when none has come yet). Each value
+  has its time, its age, its size and whether its application is still on
+  the network (`app`: `alive` / `gone` / `restarted`). Limits: 1000 keys
+  and 16 MiB kept (the oldest forgotten first), a put over 256 KiB as its
+  size only, a value's JSON cut at 8192 bytes in an answer
+  (`truncated`), 100 keys an answer (`more`). A viewer's certificate is
+  enough. README "MCP".
+- `asterism object get PATH [KEY]`: the next value the application puts
+  there (`--timeout`, 5 s). `asterism object echo PATH [KEY]`: the values
+  as they come (the text: a key's value whole, then what changed;
+  `--raw`, `--once`, `--duration`). `-o json` / `-o yaml`, and Tab
+  completion of `PATH`. Both say so when nothing came (not readable, or
+  not changed).
+- The other tools, commands and their output (`--json` too) are as they
+  were; `asterism --help`, `asterism object` and the MCP server's
+  instructions mention the new ones.
+
 ## 0.9.0
 
 The command line only; the library and the wire are as in 0.8.0 (0.8.1

data/README.md

@@ -85,7 +85,7 @@ time is taken, on both APIs and every Ruby; giving one twice raises
 
 ## Using it
 
-CRuby (needs CRuby 3.2+ and a C compiler):
+CRuby (needs CRuby 3.4+ and a C compiler):
 
 ```
 gem install asterism          # also installs asterism-zenoh (>= 0.4.1, < 1.0) and msgpack
@@ -101,7 +101,7 @@ build but not yet tested. To install from the repositories instead:
 
 ```
 (cd ../asterism-zenoh && rake gem) && rake gem
-gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.1.gem pkg/asterism-0.9.0.gem
+gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.1.gem pkg/asterism-0.10.0.gem
 ```
 
 From the working trees, without installing:
@@ -427,6 +427,8 @@ asterism app info    games/games                    # its status and its objects
 asterism object list 'games/games/*'                # node/app/object, a line each
 asterism object info games/games/othello1           # its description and its methods
 asterism object find join                           # the objects that have join (* as a wildcard)
+asterism object get  games/games/othello1 state     # the next value the application puts there
+asterism object echo games/games/othello1 state     # the values as they come (what changed)
 asterism status get  games/games                    # the status now
 asterism status echo games/games                    # the status, then each change (--once: now, once)
 asterism status hz   games/games                    # how often it changes
@@ -553,6 +555,21 @@ $ asterism watch
   only what changed: `a.b 0→1`, `+a.c=…` (a key came), `-a.d` (a key
   went). `--timeout` (2.0 s) is each get's and call's limit, `--settle`
   (1.5 s) how long it waits for the tokens after connecting.
+- **object get / echo PATH [KEY]** read what an application puts on its
+  own keys, `asterism/<node>/<app>/<object>/<more>` (docs/protocol.md 2.2;
+  a game table puts its state on `<table>/state`). `PATH` is
+  `node/app/object` (`*` for a part), `KEY` the rest (`*` and `**` as whole
+  parts; `**` by default). A put is kept nowhere and a get has no answer
+  for it, so both wait for puts: `object get` prints the next one and ends
+  (`--timeout`, 5 s; an application puts when its value changes, so a quiet
+  one gives nothing), `object echo` prints them as they come: a key's
+  value whole the first time, then only what changed in it, as
+  `status echo` does (`--raw`: each value whole; `--once`: the first put;
+  `--duration`). The value is MessagePack (Asterism's own) or JSON as it
+  is, other text as a string, bytes as their count; `-o json` gives each
+  put as `{"key", "t", "bytes", "format", "value"}`. When nothing comes
+  they say so: the router does not let this node read the key (a role
+  needs `read` on it), or nothing changed.
 - **status hz** counts the changes of the status (a put of the same status
   again is not one) and prints, every `--period` (1 s) in which a change
   came, the average rate and the intervals' min, max and standard
@@ -603,6 +620,7 @@ claude mcp add asterism -- asterism mcp --credentials admin.tar --allow 'games/o
 | `asterism_nodes` | the nodes, their profiles, applications (with their statuses) and objects |
 | `asterism_objects` | the objects and their methods (meta); `callable_as` names the tool for an allowed method |
 | `asterism_status` | the applications' statuses (`node` / `app` narrow it) |
+| `asterism_values` | the latest value of each key the applications put on (`asterism/<node>/<app>/<object>/<more>`, e.g. a game table's state), as this server received them since it started; `pattern` (`node/app/object/more`, `*` and `**`; default `**`) and `wait` (seconds, at most 30) |
 | `<node>.<app>.<object>.<method>` | one per method an `--allow` pattern names, made from the meta: the arguments' names it tells are the inputs and its doc the description (with the object's doc after it); without names, arity n gives the inputs `arg1` .. `argN` (any JSON value), arity -1 an array `args`; `kwargs` is an object of keyword arguments. The answer is `{"value": ...}`, or an error with its kind |
 
 - `--allow PATTERN` (repeatable): `[node/][app/]object.method`, `*` within
@@ -617,6 +635,38 @@ claude mcp add asterism -- asterism mcp --credentials admin.tar --allow 'games/o
   gives the MCP client its own seat. `--app` names this application (a
   game host that follows its players by the application `game` sees an
   MCP client started with `--app game` come and go).
+- **asterism_values**: from its start the server subscribes to
+  `asterism/**` (the applications' own keys; `@profile` and `@status` are
+  not under it) and keeps the last value of each key with the time it
+  came. A put comes only when a value changes and is kept nowhere else, so
+  a key that has not been put since the server started is not there:
+  `wait` waits (at most 30 s) for the first put that matches when none has
+  come yet. Each value has `key`, `value`, `t`, `age_s` (seconds since it
+  came), `bytes`, `format` and `app`: `alive`, `gone` (the application is
+  not on the network now; the value is its last one, not the present) or
+  `restarted` (it left and came back after this value). A value whose JSON
+  is longer than 8192 bytes is cut (`truncated: true`, the value the start
+  of its JSON text); the server keeps at most 1000 keys and 16 MiB (the
+  key received longest ago is forgotten first; `forgotten` counts them), a
+  single put over 256 KiB as its size only, and an answer lists at most
+  100 keys (`more`). Nothing that matches: `note` says so (not put since
+  the start, or the router does not let the server read it). A console's
+  viewer role (`read` / `watch` on `asterism/**`) is enough.
+
+  Showing an othello table to an AI assistant (the game host puts the
+  table on `games/games/othello1/state` after every move):
+
+  ```
+  claude mcp add asterism -- asterism mcp --credentials viewer.tar
+  > Watch the othello game on games/games/othello1 and tell me who is winning.
+    (the assistant calls asterism_values with pattern games/games/othello1/state, wait 30)
+  {"since":"2026-10-20T02:16:50.191Z","values":[{"key":"games/games/othello1/state",
+   "t":"2026-10-20T02:16:58.583Z","age_s":0.4,"app":"alive","bytes":181,"format":"msgpack",
+   "value":{"v":15,"t":"othello1","st":"play","nm":["CPU","Alice"],"sk":[2,1],...,
+            "bd":"..W.......W.......WBWWW...WBB....W.BBB..........................",
+            "tn":0,"n":10,"last":"c1","lg":"b1b2e2f2g2b3h3b4a6","cnt":[6,8]}}]}
+  ```
+
 - An object that describes its methods at `expose` (`args:` and `doc:`,
   "Describing the methods" below) gives the AI assistant the names and the
   texts; without them it sees only the number of arguments.

data/lib/asterism/cli/complete.rb

@@ -82,7 +82,8 @@ module Asterism
         case [key, i]
         when ["node info", 0] then nodes
         when ["app info", 0], ["status get", 0], ["status echo", 0], ["status hz", 0] then staged(cur, apps, 2)
-        when ["object list", 0], ["object info", 0], ["objects", 0], ["call", 0] then staged(cur, objects, 3)
+        when ["object list", 0], ["object info", 0], ["object get", 0], ["object echo", 0], ["objects", 0], ["call", 0]
+          staged(cur, objects, 3)
         when ["ping", 0], ["echo", 0] then (cur.include?("/") ? [] : nodes) + staged(cur, objects, 3)
         when ["object find", 0] then @source.all_methods || []
         when ["call", 1] then methods_of(args[0])

data/lib/asterism/cli/mcp.rb

@@ -9,6 +9,10 @@
 #                      and objects                         (always; reads)
 #   asterism_objects   the objects and their methods (meta) (always; reads)
 #   asterism_status    the applications' statuses           (always; reads)
+#   asterism_values    the latest value of each key the applications put
+#                      on (asterism/<node>/<app>/<object>/<more>), as this
+#                      server received them since it started (always;
+#                      reads; lib/asterism/cli/values.rb)
 #   <node>.<app>.<object>.<method>
 #                      one per method that an --allow pattern names, made
 #                      from the object's meta: the arguments' names the
@@ -30,7 +34,8 @@ module Asterism
         These tools look at an Asterism network: Ruby programs and boards that expose objects to each other over
         Zenoh. Paths are <node>/<app>/<object>. asterism_nodes lists the nodes and their applications (with the
         status each application tells about itself, a JSON object of its own), asterism_objects the objects and
-        their methods, asterism_status the statuses. The other tools call one method each, on the object their
+        their methods, asterism_status the statuses, asterism_values the latest values the applications put on
+        their own keys (a game table's state). The other tools call one method each, on the object their
         name says (<node>.<app>.<object>.<method>); only the methods this server was started to allow are there.
         A call's answer is {"value": ...}; an error says its kind (raised, not_exposed, arguments, ...).
       TEXT
@@ -43,13 +48,17 @@ module Asterism
         @call_tools = {}  # tool name => [path, method, arity, meta entry]
         @signature = nil
         @lock = Mutex.new
+        @values = Values::Store.new(alive: ->(app) { !::Asterism.apps(app).empty? })
       end
 
+      attr_reader :values
+
       def run
         @server = ::MCP::Server.new(name: "asterism", version: ::Asterism::VERSION, instructions: INSTRUCTIONS,
                                     tools: read_tools)
         @transport = ::MCP::Server::Transports::StdioTransport.new(@server)
         @server.transport = @transport
+        remember_values
         refresh
         @log.puts "asterism mcp: #{@net.node_id}/#{@net.app}; #{@call_tools.size} call tools" \
                   "#{@allow.empty? ? ' (no --allow: read-only)' : ''}"
@@ -59,6 +68,16 @@ module Asterism
         @refresher&.kill
       end
 
+      # From now on, the puts on the applications' own keys (asterism/**
+      # does not match @profile and @status), and the applications that
+      # leave (their values are marked).
+      def remember_values
+        @net.session.subscribe("#{Values::PREFIX}**", depth: 1024) { |s| @values.put(s.key, s.payload) }
+        @net.session.liveliness_watch("#{Values::PREFIX}*/*", depth: 1024) do |key, alive|
+          @values.left(key.delete_prefix(Values::PREFIX)) unless alive
+        end
+      end
+
       # ------------------------------------------------------------ the list
 
       def refresh_loop
@@ -153,10 +172,46 @@ module Asterism
                 (node.nil? || node == n) && (app.nil? || app == a)
               end
             end
+          end,
+          ::MCP::Tool.define(
+            name: "asterism_values",
+            description: VALUES_DOC,
+            input_schema: {
+              properties: {
+                pattern: { type: "string",
+                           description: "keys as node/app/object/more, with * (one part) and ** (any parts); " \
+                                        "default ** (every key). A key always has a part after the object: " \
+                                        "games/games/othello1/** or games/*/*/state, not games/games/othello1" },
+                wait: { type: "number",
+                        description: "seconds (at most #{Values::Store::MAX_WAIT}) to wait for the first put " \
+                                     "that matches when none has come yet; default 0 (answer now)" }
+              }
+            },
+            annotations: { read_only_hint: true }
+          ) do |server_context:, pattern: "**", wait: 0|
+            bridge.answer { bridge.values.answer(pattern, wait: wait) }
+          rescue ArgumentError => e
+            bridge.error(e.message)
           end
         ]
       end
 
+      VALUES_DOC = "The latest value each application put on its own keys (asterism/<node>/<app>/<object>/<more>: " \
+                   "a game table's state, a log), as this server received them: {\"since\", \"values\": " \
+                   "[{\"key\", \"value\", \"t\", \"age_s\", \"app\", \"bytes\", \"format\"}]}. " \
+                   "A put comes only when the value changes, and this server remembers only what it received " \
+                   "since it started (since): a key that has not been put since then is not listed. Give wait " \
+                   "(seconds) to wait for the first put that matches when none has come yet (a quiet table, " \
+                   "just after the start). age_s: seconds since it came. app: alive; gone (the application is " \
+                   "not on the network now: this is its last value, not the present); restarted (it left and " \
+                   "came back after this value). value: MessagePack or JSON as it is, text as a string; a " \
+                   "value whose JSON is longer than #{Values::Store::VALUE_CUT} bytes is cut (truncated: " \
+                   "true, value: the start of its JSON text). It keeps at most #{Values::Store::MAX_KEYS} keys " \
+                   "(those received longest ago are forgotten first) and lists at most " \
+                   "#{Values::Store::MAX_ANSWER} (more: how many it left out). Nothing came: the note says so " \
+                   "(not put since the start, or the router does not let this server read it). The statuses " \
+                   "(@status) are asterism_status's."
+
       def objects(pattern)
         paths = @survey.objects(pattern)
         metas = @survey.metas(paths)

data/lib/asterism/cli/nouns.rb

@@ -117,6 +117,68 @@ module Asterism
       0
     end
 
+    # The next value the application puts on its own keys (PATH/KEY: a put
+    # is kept nowhere, so it waits for one; --timeout, 5.0 s).
+    def cmd_object_get(rest)
+      pattern = put_pattern!(rest, "object get")
+      wait = @opts[:put_timeout] || 5.0
+      raise ArgumentError, "--timeout: more than 0" unless wait.positive?
+      code = 0
+      connect do |net, _sv|
+        q = Queue.new
+        net.session.subscribe(Values.key_expr(pattern), depth: 16) { |s| q << [s.key, s.payload, Time.now] }
+        got = q.pop(timeout: wait)
+        if got.nil?
+          @err.puts nothing_came(pattern, wait)
+          code = 1
+          next
+        end
+        e = Values.entry(*got)
+        if structured?
+          emit(e)
+        else
+          put_lines(got[2], e, nil).each { @out.puts _1 }
+        end
+      end
+      code
+    end
+
+    # The values the application puts on its own keys, as they come: the
+    # text shows a key's value whole the first time (and always with
+    # --raw), then what changed; -o json / yaml each put whole.
+    def cmd_object_echo(rest)
+      pattern = put_pattern!(rest, "object echo")
+      code = 0
+      connect do |net, _sv|
+        q = Queue.new
+        net.session.subscribe(Values.key_expr(pattern), depth: 256) { |s| q << [s.key, s.payload, Time.now] }
+        seen = 0
+        last = {}
+        until_stopped(net) do |left|
+          got = q.pop(timeout: [left || 0.2, 0.2].min)
+          next unless got
+          seen += 1
+          e = Values.entry(*got)
+          if structured?
+            emit_line(e)
+          else
+            whole = @opts[:raw] || !last.key?(e["key"])
+            old = last[e["key"]]
+            last[e["key"]] = e["value"]
+            lines = whole ? put_lines(got[2], e, nil) : put_lines(got[2], e, old, again: true)
+            lines&.each { @out.puts _1 }
+          end
+          @out.flush
+          break if @opts[:once]
+        end
+        if seen.zero?
+          @err.puts nothing_came(pattern, @opts[:duration])
+          code = 1 if @opts[:once]
+        end
+      end
+      code
+    end
+
     # ------------------------------------------------------------ status
 
     def cmd_status_get(rest)
@@ -314,6 +376,41 @@ module Asterism
       path
     end
 
+    # PATH (node/app/object, * for a part) and KEY (the rest, ** by
+    # default) as one pattern.
+    def put_pattern!(rest, what)
+      path = rest.shift
+      key = rest.shift || "**"
+      parts = path.to_s.split("/", -1)
+      unless parts.size == 3 && parts.none? { _1.empty? || (_1.include?("*") && _1 != "*") }
+        raise ArgumentError, "#{what}: PATH is node/app/object (* for a part), then KEY (asterism #{what} " \
+                             "games/games/othello1 state)"
+      end
+      Values.check_pattern!("#{path}/#{key}")
+    end
+
+    def nothing_came(pattern, seconds)
+      "asterism: nothing came on #{pattern}#{seconds ? " in #{format('%g', seconds)} s" : ''} " \
+        "(the router does not let this node read it, or it has not changed)"
+    end
+
+    # The lines of one put received at t: the time, the key and the value
+    # whole; again (the key's value before was old): a line for each thing
+    # that changed in a Hash, the value whole otherwise (nil: no change).
+    def put_lines(t, e, old, again: false)
+      head = "#{paint(t.strftime('%H:%M:%S.%L'), :time)} "
+      v = e["value"]
+      if again && old.is_a?(Hash) && v.is_a?(Hash)
+        changes = Text.status_diff(old, v)
+        return nil if changes.empty?
+        return changes.map { |c| "#{head}#{paint(e['key'], :object)} #{change_text(c)}" }
+      end
+      return nil if again && old == v
+      first = "#{head}#{paint(e['key'], :object)}"
+      return ["#{first} #{Text.inline(v)}"] unless v.is_a?(Hash)
+      [first, *Text.status_lines(v, style.width, Text.width(head))]
+    end
+
     def no_status(path)
       "asterism: no status from #{path} (not there, no status, or no answer in time)"
     end

data/lib/asterism/cli/values.rb

@@ -0,0 +1,216 @@
+# The values the applications put on their own keys
+# (asterism/<node>/<app>/<object>/<more>, docs/protocol.md 2.2: a game
+# table's state, a log), for `asterism object get / echo` and the MCP
+# bridge's asterism_values. A put is not kept anywhere and a get has no
+# answer for it (an application's queryable answers only the key shapes of
+# 4.3), so the latest value is only what a subscriber received and kept:
+# Values::Store keeps it, a key at a time, within limits.
+require "json"
+
+module Asterism
+  class CLI
+    module Values
+      PREFIX = "asterism/"
+      # Characters a part of a key cannot have (2.1); * and ** are whole
+      # parts.
+      BAD = /[*$?#]/
+
+      module_function
+
+      # The pattern (node/app/object/more, * and ** as whole parts) checked;
+      # ArgumentError otherwise.
+      def check_pattern!(pattern)
+        parts = pattern.to_s.split("/", -1)
+        bad = parts.empty? || parts.any? do |p|
+          p.empty? || p.start_with?("@") || (p.match?(BAD) && !%w[* **].include?(p))
+        end
+        raise ArgumentError, "#{pattern.inspect}: a key's parts are names, * (one part) or ** (any parts)" if bad
+        pattern
+      end
+
+      # The Zenoh key expression of a pattern.
+      def key_expr(pattern)
+        "#{PREFIX}#{pattern}"
+      end
+
+      def match?(pattern, key)
+        ::Asterism.glob?(pattern, key)
+      end
+
+      # [value, format] of a payload: MessagePack (Asterism's own, 3.1);
+      # else JSON text; else UTF-8 text; else "(n bytes)". The value is
+      # what JSON can hold (bytes inside as "(n bytes)").
+      def decode(payload)
+        bytes = payload.to_s.b
+        return [nil, "empty"] if bytes.empty?
+        begin
+          return [json_safe(::MessagePack.unpack(bytes)), "msgpack"]
+        rescue StandardError
+          nil
+        end
+        text = bytes.dup.force_encoding(Encoding::UTF_8)
+        return ["(#{bytes.bytesize} bytes)", "bytes"] unless text.valid_encoding?
+        begin
+          [json_safe(JSON.parse(text)), "json"]
+        rescue JSON::ParserError
+          [text, "text"]
+        end
+      end
+
+      def json_safe(v)
+        case v
+        when Hash then v.to_h { |k, x| [k.is_a?(String) ? k : k.to_s, json_safe(x)] }
+        when Array then v.map { json_safe(_1) }
+        when String then v.encoding == Encoding::BINARY && !v.ascii_only? ? "(#{v.bytesize} bytes)" : v
+        when Float then v.finite? ? v : v.to_s
+        when Integer, true, false, nil then v
+        when Symbol then v.to_s
+        else v.inspect
+        end
+      end
+
+      def time(t)
+        t.getutc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+      end
+
+      # One put as the command line and the MCP tool show it: {"key"
+      # (without asterism/), "t", "bytes", "format", "value"}.
+      def entry(key, payload, t = Time.now)
+        value, format = decode(payload)
+        { "key" => key.delete_prefix(PREFIX), "t" => time(t), "bytes" => payload.to_s.bytesize,
+          "format" => format, "value" => value }
+      end
+
+      # The latest put of each key, as received since it was made: at most
+      # max_keys keys and max_total payload bytes (the key received
+      # longest ago is forgotten first); a payload over max_bytes is kept
+      # as its size only. Thread safe; wait blocks until a key matches.
+      class Store
+        MAX_KEYS = 1000
+        MAX_BYTES = 256 * 1024
+        MAX_TOTAL = 16 * 1024 * 1024
+        # The JSON text of a value longer than this is cut in an answer.
+        VALUE_CUT = 8192
+        # The most keys an answer lists (the rest counted as "more").
+        MAX_ANSWER = 100
+        # The longest wait an answer may ask for (seconds).
+        MAX_WAIT = 30
+
+        attr_reader :since, :forgotten
+
+        # alive: given "<node>/<app>", true when the application is on the
+        # network now. clock: the monotonic seconds (for the tests).
+        def initialize(max_keys: MAX_KEYS, max_bytes: MAX_BYTES, max_total: MAX_TOTAL, alive: nil,
+                       clock: nil, now: nil)
+          @max_keys = max_keys
+          @max_bytes = max_bytes
+          @max_total = max_total
+          @alive = alive || ->(_app) { true }
+          @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+          @now = now || -> { Time.now }
+          @since = @now.call
+          @keys = {} # key => record, the oldest received first
+          @total = 0
+          @forgotten = 0
+          @lock = Mutex.new
+          @cond = ConditionVariable.new
+        end
+
+        # A put received (key with or without asterism/).
+        def put(key, payload)
+          key = key.delete_prefix(PREFIX)
+          payload = payload.to_s
+          size = payload.bytesize
+          rec = if size > @max_bytes
+                  { "value" => "(#{size} bytes: too large to keep)", "format" => "dropped", "kept" => false }
+                else
+                  v, f = Values.decode(payload)
+                  { "value" => v, "format" => f }
+                end
+          rec.merge!("key" => key, "bytes" => size, "t" => @now.call, "mono" => @clock.call, "left" => false)
+          @lock.synchronize do
+            old = @keys.delete(key)
+            @total -= old["kept"] == false ? 0 : old["bytes"] if old
+            @keys[key] = rec
+            @total += size unless rec["kept"] == false
+            while @keys.size > @max_keys || (@total > @max_total && @keys.size > 1)
+              _, gone = @keys.shift
+              @total -= gone["bytes"] unless gone["kept"] == false
+              @forgotten += 1
+            end
+            @cond.broadcast
+          end
+          self
+        end
+
+        # The application "<node>/<app>" left the network: its values are
+        # from before (kept, marked).
+        def left(app)
+          prefix = "#{app}/"
+          @lock.synchronize { @keys.each_value { |r| r["left"] = true if r["key"].start_with?(prefix) } }
+          self
+        end
+
+        def size
+          @lock.synchronize { @keys.size }
+        end
+
+        def keys
+          @lock.synchronize { @keys.keys }
+        end
+
+        # The records whose keys match (sorted by key); with wait (seconds),
+        # until one matches or the time is up.
+        def match(pattern, wait: 0)
+          deadline = @clock.call + wait.to_f
+          @lock.synchronize do
+            loop do
+              got = @keys.values.select { Values.match?(pattern, _1["key"]) }
+              return got.sort_by { _1["key"] } unless got.empty?
+              left = deadline - @clock.call
+              return [] if left <= 0
+              @cond.wait(@lock, left)
+            end
+          end
+        end
+
+        # What asterism_values answers: {"since", "values" => [{"key", "t",
+        # "age_s", "app", "bytes", "format", "value"(, "truncated")}]}, with
+        # "more" when more keys matched than an answer lists, "forgotten"
+        # when the limits made it forget keys, and "note" when nothing came.
+        def answer(pattern = "**", wait: 0)
+          Values.check_pattern!(pattern)
+          wait = wait.to_f.clamp(0, MAX_WAIT)
+          recs = match(pattern, wait: wait)
+          now = @clock.call
+          alive = {}
+          out = { "since" => Values.time(@since) }
+          out["values"] = recs.first(MAX_ANSWER).map do |r|
+            app = r["key"].split("/")[0, 2].join("/")
+            here = alive.key?(app) ? alive[app] : (alive[app] = @alive.call(app) ? true : false)
+            h = { "key" => r["key"], "t" => Values.time(r["t"]), "age_s" => (now - r["mono"]).round(1),
+                  "app" => here ? (r["left"] ? "restarted" : "alive") : "gone", "bytes" => r["bytes"],
+                  "format" => r["format"] }
+            text = JSON.generate(r["value"])
+            if text.bytesize > VALUE_CUT
+              h["value"] = "#{text.byteslice(0, VALUE_CUT).scrub('')}…"
+              h["truncated"] = true
+            else
+              h["value"] = r["value"]
+            end
+            h["truncated"] = true if r["kept"] == false
+            h
+          end
+          out["more"] = recs.size - MAX_ANSWER if recs.size > MAX_ANSWER
+          out["forgotten"] = @forgotten if @forgotten.positive?
+          if recs.empty?
+            out["note"] = "nothing came for #{pattern}#{wait.positive? ? " in #{format('%g', wait)} s" : ''}: " \
+                          "it has not been put since this server started (puts come only when a value " \
+                          "changes), or the router does not let this server read it"
+          end
+          out
+        end
+      end
+    end
+  end
+end

data/lib/asterism/cli.rb

@@ -8,6 +8,7 @@
 #   asterism object list 'games/games/*' / object info games/games/othello1
 #   asterism object find join             # the objects that have join
 #   asterism status get  games/games      # echo: as it changes, hz: how often
+#   asterism object get  games/games/othello1 state   # the next put there
 #   asterism call        games/games/othello1 view '"<token>"'
 #   asterism ping / watch / tree / mcp    # as before
 #   asterism completion bash              # the shell's Tab completion
@@ -30,6 +31,7 @@ require_relative "cli/allow"
 require_relative "cli/text"
 require_relative "cli/hz"
 require_relative "cli/complete"
+require_relative "cli/values"
 
 module Asterism
   class CLI
@@ -46,7 +48,11 @@ module Asterism
       "object" => {
         "list" => ["[PATTERN]", "the objects, node/app/object a line (PATTERN: * and ** for whole parts)"],
         "info" => ["PATH", "one object (node/app/object): its description and its methods"],
-        "find" => ["METHOD", "the objects that have the method (* as a wildcard)"]
+        "find" => ["METHOD", "the objects that have the method (* as a wildcard)"],
+        "get" => ["PATH [KEY]", "the next value the application puts on PATH/KEY (its own keys; KEY: ** " \
+                                "by default; --timeout 5.0)"],
+        "echo" => ["PATH [KEY]", "the values it puts there as they come (the text: what changed; --once: " \
+                                 "the first; --raw: each whole)"]
       },
       "status" => {
         "get" => ["NODE/APP", "an application's status, now"],
@@ -199,7 +205,11 @@ module Asterism
             end
             o.on("--json", "JSON instead of text (-o json)") { @opts[:format] = :json }
           end
-          o.on("--timeout SECONDS", Float, "time limit of each get or call (2.0)") { @opts[:timeout] = _1 }
+          if key == "object get"
+            o.on("--timeout SECONDS", Float, "how long to wait for a put (5.0)") { @opts[:put_timeout] = _1 }
+          else
+            o.on("--timeout SECONDS", Float, "time limit of each get or call (2.0)") { @opts[:timeout] = _1 }
+          end
           o.on("--settle SECONDS", Float, "how long to wait for the tokens at connect (1.5)") { @opts[:settle] = _1 }
         end
         case key
@@ -216,6 +226,10 @@ module Asterism
         when "mcp"
           o.on("--allow PATTERN", "methods the MCP client may call: [node/][app/]object.method, * as a wildcard " \
                                   "(repeatable)") { @opts[:allow] << _1 }
+        when "object echo"
+          o.on("--once", "the first put, then stop") { @opts[:once] = true }
+          o.on("--raw", "each value whole (the text; else what changed)") { @opts[:raw] = true }
+          o.on("--duration SECONDS", Float, "stop after this long (default: until Ctrl-C)") { @opts[:duration] = _1 }
         when "status echo"
           o.on("--once", "the status now, once, then stop") { @opts[:once] = true }
           o.on("--duration SECONDS", Float, "stop after this long (default: until Ctrl-C)") { @opts[:duration] = _1 }

data/lib/asterism/version.rb

@@ -3,5 +3,5 @@ module Asterism
   # is in asterism.gemspec (asterism-zenoh ~> 0.4.0 for 0.5.0 to 0.7.0:
   # the bindings did not change; see CHANGELOG.md). 0.7.0 speaks wire
   # protocol 1 only (Asterism::PROTOCOL, docs/protocol.md).
-  VERSION = "0.9.0"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: asterism
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Katsuhiko Kageyama
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asterism-zenoh
@@ -47,7 +46,6 @@ dependencies:
 description: Proxies for objects exposed by other Ruby processes and boards, a ROS
   2 node speaking rmw_zenoh's wire format, CDR and generated message types. Pure Ruby;
   the same files are the mrbgem for mruby / PicoRuby.
-email: 
 executables:
 - asterism
 extensions: []
@@ -156,6 +154,7 @@ files:
 - lib/asterism/cli/nouns.rb
 - lib/asterism/cli/survey.rb
 - lib/asterism/cli/text.rb
+- lib/asterism/cli/values.rb
 - lib/asterism/cruby.rb
 - lib/asterism/cruby/credentials.rb
 - lib/asterism/cruby/objects.rb
@@ -182,7 +181,6 @@ metadata:
   source_code_uri: https://github.com/ruby-asterism/asterism
   bug_tracker_uri: https://github.com/ruby-asterism/asterism/issues
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -190,15 +188,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: 'Asterism: Ruby objects on other machines, and ROS 2 (rmw_zenoh) nodes, over
   Zenoh'