Skip to content

Agent Mesh

add watch functionality

Antonio Ojeaad7fec688f1e
diff --git a/cmd/sam/agent_discovery.go b/cmd/sam/agent_discovery.go
new file mode 100644
index 00000000..07abca45
--- /dev/null
+++ b/cmd/sam/agent_discovery.go
@@ -0,0 +1,142 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "strings"
+ "time"
+
+ samnet "sam/pkg/net"
+ "sam/pkg/protocol"
+)
+
+func newAgentDiscoverer(node samnet.Node, federation string, maxDHTCardAge time.Duration) (samnet.AgentDiscoverFunc, error) {
+ svc, err := protocol.NewDiscoveryService(node, protocol.WithMaxDHTCardAge(maxDHTCardAge))
+ if err != nil {
+ return nil, fmt.Errorf("creating discovery service: %w", err)
+ }
+ return func(ctx context.Context) ([]samnet.DiscoveredAgent, error) {
+ seen := map[string]samnet.DiscoveredAgent{}
+ const dhtLookupTimeout = 1200 * time.Millisecond
+
+ connectedCtx, cancelConnected := context.WithTimeout(ctx, 2*time.Second)
+ connected, err := svc.DiscoverAll(connectedCtx)
+ cancelConnected()
+ if err == nil {
+ for _, card := range connected {
+ if record, ok := discoveredAgentFromCard(card); ok {
+ seen[record.PeerID] = record
+ }
+ }
+ }
+
+ for _, id := range node.Host().Peerstore().Peers() {
+ if id == "" || id == node.PeerID() {
+ continue
+ }
+ lookupCtx, cancelLookup := context.WithTimeout(ctx, dhtLookupTimeout)
+ raw, getErr := node.GetValue(lookupCtx, protocol.DHTPeerCardKey(id.String()))
+ cancelLookup()
+ if getErr != nil {
+ continue
+ }
+ card, decodeErr := decodeAgentCardRaw(raw)
+ if decodeErr != nil {
+ continue
+ }
+ if record, ok := discoveredAgentFromCard(card); ok {
+ seen[record.PeerID] = record
+ }
+ }
+
+ for _, id := range node.Host().Network().Peers() {
+ lookupCtx, cancelLookup := context.WithTimeout(ctx, dhtLookupTimeout)
+ raw, getErr := node.GetValue(lookupCtx, protocol.DHTPeerCardKey(id.String()))
+ cancelLookup()
+ if getErr != nil {
+ continue
+ }
+ card, decodeErr := decodeAgentCardRaw(raw)
+ if decodeErr != nil {
+ continue
+ }
+ if record, ok := discoveredAgentFromCard(card); ok {
+ seen[record.PeerID] = record
+ }
+ }
+
+ capabilities, err := samnet.CachedCapabilities(federation)
+ if err == nil {
+ for _, capability := range capabilities {
+ discoverCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
+ cards, discoverErr := svc.Discover(discoverCtx, capability)
+ cancel()
+ if discoverErr != nil {
+ continue
+ }
+ for _, card := range cards {
+ if record, ok := discoveredAgentFromCard(card); ok {
+ seen[record.PeerID] = record
+ }
+ }
+ }
+ }
+
+ out := make([]samnet.DiscoveredAgent, 0, len(seen))
+ for _, record := range seen {
+ out = append(out, record)
+ }
+ return out, nil
+ }, nil
+}
+
+func discoveredAgentFromCard(card *protocol.AgentCard) (samnet.DiscoveredAgent, bool) {
+ if card == nil || strings.TrimSpace(card.PeerID) == "" {
+ return samnet.DiscoveredAgent{}, false
+ }
+ raw, err := json.Marshal(card)
+ if err != nil {
+ return samnet.DiscoveredAgent{}, false
+ }
+ return samnet.DiscoveredAgent{
+ PeerID: card.PeerID,
+ Card: raw,
+ Capabilities: card.CapabilityNames(),
+ }, true
+}
+
+func decodeCachedAgentCards(federation string) ([]*protocol.AgentCard, error) {
+ records, err := samnet.LoadCachedAgentRecords(federation)
+ if err != nil {
+ return nil, err
+ }
+ out := make([]*protocol.AgentCard, 0, len(records))
+ for _, record := range records {
+ card, err := decodeAgentCardRaw(record.Card)
+ if err != nil {
+ continue
+ }
+ out = append(out, card)
+ }
+ return out, nil
+}
+
+func upsertAgentCardRecord(federation string, card *protocol.AgentCard) error {
+ record, ok := discoveredAgentFromCard(card)
+ if !ok {
+ return nil
+ }
+ return samnet.UpsertCachedAgentRecord(federation, record)
+}
+
+func decodeAgentCardRaw(raw []byte) (*protocol.AgentCard, error) {
+ var card protocol.AgentCard
+ if err := json.Unmarshal(raw, &card); err != nil {
+ return nil, fmt.Errorf("decoding agent card: %w", err)
+ }
+ if err := protocol.VerifyAgentCard(&card); err != nil {
+ return nil, fmt.Errorf("validating agent card: %w", err)
+ }
+ return &card, nil
+}
diff --git a/cmd/sam/mesh_get_agents.go b/cmd/sam/mesh_get_agents.go
index e54cf164..85b29263 100644
--- a/cmd/sam/mesh_get_agents.go
+++ b/cmd/sam/mesh_get_agents.go
@@ -1,14 +1,21 @@
package main
import (
+ "bufio"
"context"
+ "encoding/json"
"fmt"
+ "io"
+ "net/http"
+ "net/http/httptest"
"os"
+ "strings"
"time"
"github.com/libp2p/go-libp2p/core/peer"
"github.com/spf13/cobra"
+ samnet "sam/pkg/net"
"sam/pkg/protocol"
)
@@ -37,6 +44,7 @@ Examples:
"how long to wait for DHT discovery when --capability is set")
cmd.Flags().DurationVar(&cfg.dhtCardMaxAge, "dht-card-max-age", 15*time.Minute,
"maximum accepted age for DHT-fetched cards (<=0 disables freshness check)")
+ cmd.Flags().BoolVar(&cfg.meshWatch, "watch", false, "watch for newly discovered agents and append them live")
return cmd
}
@@ -55,6 +63,10 @@ func runMeshGetAgents(parent context.Context, cfg *runConfig) error {
}
defer func() { _ = node.Stop(context.Background()) }()
+ if cfg.meshWatch {
+ return runMeshGetAgentsWatch(parent, cfg, format, node)
+ }
+
svc, err := protocol.NewDiscoveryService(node, protocol.WithMaxDHTCardAge(cfg.dhtCardMaxAge))
if err != nil {
return fmt.Errorf("creating discovery service: %w", err)
@@ -89,3 +101,118 @@ func runMeshGetAgents(parent context.Context, cfg *runConfig) error {
return printAgents(os.Stdout, cards, format, latencyByPeer)
}
+
+func runMeshGetAgentsWatch(parent context.Context, cfg *runConfig, format outputFormat, node samnet.Node) error {
+ watchManager, err := newInventoryWatchManager(node, cfg.federation)
+ if err != nil {
+ return fmt.Errorf("creating inventory watch manager: %w", err)
+ }
+ defer watchManager.Close()
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/.sam/watch/inventory" {
+ http.NotFound(w, r)
+ return
+ }
+ watchManager.ServeInventoryWatch(w, r)
+ }))
+ defer server.Close()
+
+ req, err := http.NewRequestWithContext(parent, http.MethodGet, server.URL+"/.sam/watch/inventory", nil)
+ if err != nil {
+ return fmt.Errorf("building watch request: %w", err)
+ }
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ return fmt.Errorf("opening watch stream: %w", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+ if resp.StatusCode != http.StatusOK {
+ body, _ := io.ReadAll(resp.Body)
+ return fmt.Errorf("watch stream failed: %s: %s", resp.Status, strings.TrimSpace(string(body)))
+ }
+
+ discoverer, err := newAgentDiscoverer(node, cfg.federation, cfg.dhtCardMaxAge)
+ if err != nil {
+ return fmt.Errorf("creating informer discoverer: %w", err)
+ }
+ informer, err := samnet.NewLocalInformer(node, cfg.federation, samnet.WithInformerDiscoverer(discoverer))
+ if err != nil {
+ return fmt.Errorf("creating local informer: %w", err)
+ }
+ informer.Start(parent)
+
+ if format == outputTable {
+ if err := printAgentsTableHeader(os.Stdout); err != nil {
+ return err
+ }
+ }
+
+ seen := map[string]struct{}{}
+ return consumeInventorySSE(resp.Body, func(evt samnet.AgentWatchEvent) error {
+ if evt.Type != samnet.AgentWatchEventAdded || len(evt.Card) == 0 {
+ return nil
+ }
+ card, err := decodeAgentCardRaw(evt.Card)
+ if err != nil {
+ return nil
+ }
+ if _, ok := seen[card.PeerID]; ok {
+ return nil
+ }
+ seen[card.PeerID] = struct{}{}
+
+ latencyByPeer := map[string]time.Duration{}
+ if id, err := peer.Decode(card.PeerID); err == nil {
+ latencyByPeer[card.PeerID] = node.Host().Peerstore().LatencyEWMA(id)
+ }
+ rows := toAgentRows([]*protocol.AgentCard{card}, latencyByPeer)
+ if format == outputJSON {
+ enc := json.NewEncoder(os.Stdout)
+ return enc.Encode(rows[0])
+ }
+ return printAgentRows(os.Stdout, rows)
+ })
+}
+
+func consumeInventorySSE(body io.Reader, onEvent func(samnet.AgentWatchEvent) error) error {
+ scanner := bufio.NewScanner(body)
+ var eventName string
+ var dataLines []string
+ for scanner.Scan() {
+ line := scanner.Text()
+ if line == "" {
+ if strings.EqualFold(eventName, "HEARTBEAT") {
+ eventName = ""
+ dataLines = nil
+ continue
+ }
+ if len(dataLines) > 0 {
+ var evt samnet.AgentWatchEvent
+ if err := json.Unmarshal([]byte(strings.Join(dataLines, "\n")), &evt); err != nil {
+ return fmt.Errorf("decoding watch event: %w", err)
+ }
+ if evt.Type == "" {
+ evt.Type = samnet.AgentWatchEventType(eventName)
+ }
+ if err := onEvent(evt); err != nil {
+ return err
+ }
+ }
+ eventName = ""
+ dataLines = nil
+ continue
+ }
+ if strings.HasPrefix(line, "event: ") {
+ eventName = strings.TrimSpace(strings.TrimPrefix(line, "event: "))
+ continue
+ }
+ if strings.HasPrefix(line, "data: ") {
+ dataLines = append(dataLines, strings.TrimPrefix(line, "data: "))
+ }
+ }
+ if err := scanner.Err(); err != nil {
+ return err
+ }
+ return nil
+}
diff --git a/cmd/sam/output.go b/cmd/sam/output.go
index c394583d..f3528690 100644
--- a/cmd/sam/output.go
+++ b/cmd/sam/output.go
@@ -104,6 +104,26 @@ func printAgentsTable(w io.Writer, rows []agentRow) error {
return tw.Flush()
}
+func printAgentsTableHeader(w io.Writer) error {
+ tw := tabwriter.NewWriter(w, 0, 0, 3, ' ', 0)
+ _, _ = fmt.Fprintln(tw, "PEER ID\tIDENTITY\tCAPABILITY\tLATENCY\tISSUED AT")
+ return tw.Flush()
+}
+
+func printAgentRows(w io.Writer, rows []agentRow) error {
+ tw := tabwriter.NewWriter(w, 0, 0, 3, ' ', 0)
+ for _, r := range rows {
+ _, _ = fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n",
+ truncate(r.PeerID, 20),
+ r.Identity,
+ r.Capability,
+ r.Latency,
+ r.IssuedAt.Format(time.RFC3339),
+ )
+ }
+ return tw.Flush()
+}
+
func truncate(s string, n int) string {
if len(s) <= n {
return s
diff --git a/cmd/sam/proxy.go b/cmd/sam/proxy.go
index dfa66c01..de2880da 100644
--- a/cmd/sam/proxy.go
+++ b/cmd/sam/proxy.go
@@ -8,8 +8,6 @@ import (
"log/slog"
"math/big"
"net/http"
- "os"
- "path/filepath"
"sort"
"strconv"
"strings"
@@ -19,18 +17,11 @@ import (
"github.com/libp2p/go-libp2p/core/peer"
"github.com/multiformats/go-multihash"
"github.com/spf13/cobra"
- "go.etcd.io/bbolt"
- internaldb "sam/internal/db"
samnet "sam/pkg/net"
"sam/pkg/protocol"
)
-const (
- proxyCacheRecordVersion = 1
- proxyCacheCardPrefix = "agent-card/"
-)
-
func newProxyCmd(cfg *runConfig) *cobra.Command {
cmd := &cobra.Command{
Use: "proxy",
@@ -75,9 +66,25 @@ func runProxy(parent context.Context, cfg *runConfig) error {
}
defer func() { _ = node.Stop(context.Background()) }()
+ discoverer, err := newAgentDiscoverer(node, cfg.federation, 15*time.Minute)
+ if err != nil {
+ return fmt.Errorf("creating informer discoverer: %w", err)
+ }
+ informer, err := samnet.NewLocalInformer(node, cfg.federation, samnet.WithInformerDiscoverer(discoverer))
+ if err != nil {
+ return fmt.Errorf("creating local informer: %w", err)
+ }
+ informer.Start(parent)
+
+ watchManager, err := newInventoryWatchManager(node, cfg.federation)
+ if err != nil {
+ return fmt.Errorf("creating inventory watch manager: %w", err)
+ }
+ defer watchManager.Close()
+
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if strings.HasPrefix(r.URL.Path, "/.sam/") {
- handleSAMReserved(w, r, node, cfg)
+ handleSAMReservedWithWatcher(w, r, node, cfg, watchManager)
return
}
@@ -188,10 +195,25 @@ func runProxy(parent context.Context, cfg *runConfig) error {
}
func handleSAMReserved(w http.ResponseWriter, r *http.Request, node samnet.Node, cfg *runConfig) {
+ handleSAMReservedWithWatcher(w, r, node, cfg, nil)
+}
+
+func handleSAMReservedWithWatcher(w http.ResponseWriter, r *http.Request, node samnet.Node, cfg *runConfig, watchManager *inventoryWatchManager) {
ctx, cancel := context.WithTimeout(r.Context(), cfg.proxyTimeout)
defer cancel()
switch r.URL.Path {
+ case "/.sam/watch/inventory":
+ if r.Method != http.MethodGet {
+ http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+ return
+ }
+ if watchManager == nil {
+ http.Error(w, "watch manager unavailable", http.StatusServiceUnavailable)
+ return
+ }
+ watchManager.ServeInventoryWatch(w, r)
+ return
case "/.sam/inventory":
if r.Method != http.MethodGet {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
@@ -236,7 +258,7 @@ func handleSAMReserved(w http.ResponseWriter, r *http.Request, node samnet.Node,
}
func aggregateInventory(ctx context.Context, node samnet.Node, federation string) ([]*protocol.AgentCard, error) {
- cached, err := loadCachedCards(federation)
+ cached, err := decodeCachedAgentCards(federation)
if err != nil {
return nil, err
}
@@ -263,7 +285,7 @@ func aggregateInventory(ctx context.Context, node samnet.Node, federation string
continue
}
byPeer[card.PeerID] = card
- _ = cacheCard(federation, card)
+ _ = upsertAgentCardRecord(federation, card)
}
}
@@ -278,7 +300,7 @@ func aggregateInventory(ctx context.Context, node samnet.Node, federation string
func searchInventoryBySkill(ctx context.Context, node samnet.Node, federation, skill string) ([]*protocol.AgentCard, error) {
byPeer := map[string]*protocol.AgentCard{}
- cached, _ := loadCachedCards(federation)
+ cached, _ := decodeCachedAgentCards(federation)
for _, card := range cached {
if cardHasCapability(card, skill) {
byPeer[card.PeerID] = card
@@ -296,7 +318,7 @@ func searchInventoryBySkill(ctx context.Context, node samnet.Node, federation, s
continue
}
byPeer[card.PeerID] = card
- _ = cacheCard(federation, card)
+ _ = upsertAgentCardRecord(federation, card)
}
}
@@ -410,100 +432,6 @@ func cardHasCapability(card *protocol.AgentCard, capability string) bool {
return false
}
-func cacheCard(federation string, card *protocol.AgentCard) error {
- if card == nil || strings.TrimSpace(card.PeerID) == "" {
- return nil
- }
- path, err := federationDBPath(federation)
- if err != nil {
- return err
- }
- db, err := bbolt.Open(path, 0o600, &bbolt.Options{Timeout: 2 * time.Second})
- if err != nil {
- return err
- }
- defer func() { _ = db.Close() }()
-
- codec := internaldb.JSONCodec{}
- payload, err := codec.Marshal(proxyCacheRecordVersion, card)
- if err != nil {
- return err
- }
- key := proxyCacheCardPrefix + card.PeerID
- return db.Update(func(tx *bbolt.Tx) error {
- bucket := tx.Bucket([]byte(internaldb.BucketCache))
- if bucket == nil {
- return fmt.Errorf("missing cache bucket")
- }
- return bucket.Put([]byte(key), payload)
- })
-}
-
-func loadCachedCards(federation string) ([]*protocol.AgentCard, error) {
- path, err := federationDBPath(federation)
- if err != nil {
- return nil, err
- }
- if _, err := os.Stat(path); err != nil {
- if os.IsNotExist(err) {
- return nil, nil
- }
- return nil, err
- }
- db, err := bbolt.Open(path, 0o600, &bbolt.Options{Timeout: 2 * time.Second, ReadOnly: true})
- if err != nil {
- return nil, err
- }
- defer func() { _ = db.Close() }()
-
- codec := internaldb.JSONCodec{}
- seen := map[string]struct{}{}
- out := make([]*protocol.AgentCard, 0)
- err = db.View(func(tx *bbolt.Tx) error {
- bucket := tx.Bucket([]byte(internaldb.BucketCache))
- if bucket == nil {
- return nil
- }
- return bucket.ForEach(func(key, value []byte) error {
- if !strings.HasPrefix(string(key), proxyCacheCardPrefix) {
- return nil
- }
- var card protocol.AgentCard
- if err := codec.Unmarshal(value, proxyCacheRecordVersion, &card, nil); err != nil {
- return nil
- }
- if err := protocol.VerifyAgentCard(&card); err != nil {
- return nil
- }
- if _, ok := seen[card.PeerID]; ok {
- return nil
- }
- seen[card.PeerID] = struct{}{}
- out = append(out, &card)
- return nil
- })
- })
- if err != nil {
- return nil, err
- }
- return out, nil
-}
-
-func federationDBPath(federation string) (string, error) {
- baseDir, err := internaldb.FederationsDir()
- if err != nil {
- return "", err
- }
- name := strings.TrimSpace(federation)
- if name == "" {
- name = "default"
- }
- if err := os.MkdirAll(baseDir, 0o700); err != nil {
- return "", err
- }
- return filepath.Join(baseDir, name+".db"), nil
-}
-
type meshToolEntry struct {
URI string `json:"uri"`
PeerID string `json:"peer_id"`
diff --git a/cmd/sam/proxy_reserved_test.go b/cmd/sam/proxy_reserved_test.go
index 45eff59b..d665b296 100644
--- a/cmd/sam/proxy_reserved_test.go
+++ b/cmd/sam/proxy_reserved_test.go
@@ -1,5 +1,4 @@
package main
-package main
import (
"context"
diff --git a/cmd/sam/proxy_watch.go b/cmd/sam/proxy_watch.go
new file mode 100644
index 00000000..58961745
--- /dev/null
+++ b/cmd/sam/proxy_watch.go
@@ -0,0 +1,170 @@
+package main
+
+import (
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "sync"
+ "time"
+
+ "github.com/libp2p/go-libp2p/core/event"
+
+ samnet "sam/pkg/net"
+)
+
+const proxyWatchHeartbeatInterval = 15 * time.Second
+
+type inventoryWatchManager struct {
+ federation string
+ sub event.Subscription
+
+ mu sync.Mutex
+ nextID uint64
+ watchers map[uint64]chan samnet.AgentWatchEvent
+ closed bool
+}
+
+func newInventoryWatchManager(node samnet.Node, federation string) (*inventoryWatchManager, error) {
+ sub, err := node.Host().EventBus().Subscribe(new(samnet.AgentWatchEvent))
+ if err != nil {
+ return nil, fmt.Errorf("subscribing to agent watch events: %w", err)
+ }
+ mgr := &inventoryWatchManager{
+ federation: federation,
+ sub: sub,
+ watchers: map[uint64]chan samnet.AgentWatchEvent{},
+ }
+ go mgr.run()
+ return mgr, nil
+}
+
+func (m *inventoryWatchManager) Close() error {
+ m.mu.Lock()
+ if m.closed {
+ m.mu.Unlock()
+ return nil
+ }
+ m.closed = true
+ watchers := m.watchers
+ m.watchers = map[uint64]chan samnet.AgentWatchEvent{}
+ m.mu.Unlock()
+ for id, ch := range watchers {
+ close(ch)
+ delete(watchers, id)
+ }
+ return m.sub.Close()
+}
+
+func (m *inventoryWatchManager) run() {
+ for evt := range m.sub.Out() {
+ switch agentEvent := evt.(type) {
+ case samnet.AgentWatchEvent:
+ m.broadcast(agentEvent)
+ case *samnet.AgentWatchEvent:
+ if agentEvent != nil {
+ m.broadcast(*agentEvent)
+ }
+ }
+ }
+}
+
+func (m *inventoryWatchManager) register() (uint64, <-chan samnet.AgentWatchEvent) {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ id := m.nextID
+ m.nextID++
+ ch := make(chan samnet.AgentWatchEvent, 32)
+ m.watchers[id] = ch
+ return id, ch
+}
+
+func (m *inventoryWatchManager) unregister(id uint64) {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ if ch, ok := m.watchers[id]; ok {
+ delete(m.watchers, id)
+ close(ch)
+ }
+}
+
+func (m *inventoryWatchManager) broadcast(evt samnet.AgentWatchEvent) {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ for _, ch := range m.watchers {
+ select {
+ case ch <- evt:
+ default:
+ }
+ }
+}
+
+func (m *inventoryWatchManager) ServeInventoryWatch(w http.ResponseWriter, r *http.Request) {
+ flusher, ok := w.(http.Flusher)
+ if !ok {
+ http.Error(w, "streaming not supported", http.StatusInternalServerError)
+ return
+ }
+
+ w.Header().Set("Content-Type", "text/event-stream")
+ w.Header().Set("Cache-Control", "no-cache")
+ w.Header().Set("Connection", "keep-alive")
+ w.Header().Set("X-Accel-Buffering", "no")
+ id, ch := m.register()
+ defer m.unregister(id)
+
+ if err := writeSSEHeartbeat(w); err != nil {
+ return
+ }
+ flusher.Flush()
+
+ records, _ := samnet.LoadCachedAgentRecords(m.federation)
+ for _, record := range records {
+ if err := writeSSEEvent(w, samnet.AgentWatchEvent{Type: samnet.AgentWatchEventAdded, PeerID: record.PeerID, Card: record.Card}); err != nil {
+ return
+ }
+ flusher.Flush()
+ }
+
+ heartbeat := time.NewTicker(proxyWatchHeartbeatInterval)
+ defer heartbeat.Stop()
+
+ for {
+ select {
+ case <-r.Context().Done():
+ return
+ case evt, ok := <-ch:
+ if !ok {
+ return
+ }
+ if err := writeSSEEvent(w, evt); err != nil {
+ return
+ }
+ flusher.Flush()
+ case <-heartbeat.C:
+ if err := writeSSEHeartbeat(w); err != nil {
+ return
+ }
+ flusher.Flush()
+ }
+ }
+}
+func writeSSEEvent(w http.ResponseWriter, evt samnet.AgentWatchEvent) error {
+ data, err := json.Marshal(evt)
+ if err != nil {
+ return err
+ }
+ if _, err := fmt.Fprintf(w, "event: %s\n", evt.Type); err != nil {
+ return err
+ }
+ if _, err := fmt.Fprintf(w, "data: %s\n\n", data); err != nil {
+ return err
+ }
+ return nil
+}
+
+func writeSSEHeartbeat(w http.ResponseWriter) error {
+ if _, err := fmt.Fprint(w, "event: HEARTBEAT\ndata: {}\n\n"); err != nil {
+ return err
+ }
+ return nil
+}
diff --git a/cmd/sam/publish.go b/cmd/sam/publish.go
index b696a1dc..b47520cc 100644
--- a/cmd/sam/publish.go
+++ b/cmd/sam/publish.go
@@ -111,6 +111,9 @@ func runPublish(parent context.Context, cfg *runConfig) error {
if err := attachNodeVouch(card, node.PeerID().String(), priv); err != nil {
return err
}
+ if err := registerLocalAgentCard(node, card); err != nil {
+ return err
+ }
// For dry-run=server mode, skip DHT but still build network
if cfg.dryRun == "server" {
@@ -178,6 +181,17 @@ func nodeEd25519PrivateKey(priv any) (ed25519.PrivateKey, error) {
return ed25519.PrivateKey(raw), nil
}
+func registerLocalAgentCard(node samnet.Node, card *protocol.AgentCard) error {
+ svc, err := protocol.NewDiscoveryService(node)
+ if err != nil {
+ return fmt.Errorf("creating local discovery service: %w", err)
+ }
+ if err := svc.RegisterLocalCard(card); err != nil {
+ return fmt.Errorf("registering local agent card stream: %w", err)
+ }
+ return nil
+}
+
func publishLoop(parent context.Context, pub *protocol.Publisher, card *protocol.AgentCard, every time.Duration) error {
if every <= 0 {
every = 2 * time.Minute
diff --git a/cmd/sam/publish_card.go b/cmd/sam/publish_card.go
index 94a8d1a9..68d29024 100644
--- a/cmd/sam/publish_card.go
+++ b/cmd/sam/publish_card.go
@@ -58,6 +58,9 @@ func runPublishCard(parent context.Context, cfg *runConfig) error {
if err := attachNodeVouch(card, node.PeerID().String(), priv); err != nil {
return err
}
+ if err := registerLocalAgentCard(node, card); err != nil {
+ return err
+ }
pub, err := protocol.NewPublisher(node)
if err != nil {
diff --git a/cmd/sam/publish_mcp.go b/cmd/sam/publish_mcp.go
index a036a032..af66cf29 100644
--- a/cmd/sam/publish_mcp.go
+++ b/cmd/sam/publish_mcp.go
@@ -66,6 +66,9 @@ func runPublishMCP(parent context.Context, cfg *runConfig) error {
if err := attachNodeVouch(card, node.PeerID().String(), priv); err != nil {
return err
}
+ if err := registerLocalAgentCard(node, card); err != nil {
+ return err
+ }
connector := &httpMCPConnector{
client: &http.Client{Timeout: 30 * time.Second},
diff --git a/cmd/sam/root.go b/cmd/sam/root.go
index d2e89b79..421bc214 100644
--- a/cmd/sam/root.go
+++ b/cmd/sam/root.go
@@ -43,6 +43,7 @@ type runConfig struct {
capability string
discoverTimeout time.Duration
dhtCardMaxAge time.Duration
+ meshWatch bool
// sam call
callMessage string
diff --git a/pkg/net/informer.go b/pkg/net/informer.go
new file mode 100644
index 00000000..eb17b1c8
--- /dev/null
+++ b/pkg/net/informer.go
@@ -0,0 +1,278 @@
+package samnet
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/libp2p/go-libp2p/core/event"
+ "go.etcd.io/bbolt"
+
+ internaldb "sam/internal/db"
+)
+
+const (
+ agentCacheRecordVersion = 1
+ agentCacheCardPrefix = "agent-card/"
+ defaultInformerPeriod = 2 * time.Second
+)
+
+type AgentWatchEventType string
+
+const (
+ AgentWatchEventAdded AgentWatchEventType = "ADDED"
+)
+
+type AgentWatchEvent struct {
+ Type AgentWatchEventType `json:"type"`
+ PeerID string `json:"peer_id,omitempty"`
+ Card json.RawMessage `json:"card,omitempty"`
+}
+
+type DiscoveredAgent struct {
+ PeerID string
+ Card []byte
+ Capabilities []string
+}
+
+type AgentDiscoverFunc func(context.Context) ([]DiscoveredAgent, error)
+
+type LocalInformer struct {
+ node Node
+ federation string
+ interval time.Duration
+ emitter event.Emitter
+ discover AgentDiscoverFunc
+
+ mu sync.Mutex
+ knownByID map[string]string
+}
+
+type LocalInformerOption func(*LocalInformer)
+
+func WithInformerInterval(interval time.Duration) LocalInformerOption {
+ return func(informer *LocalInformer) {
+ informer.interval = interval
+ }
+}
+
+func WithInformerDiscoverer(discover AgentDiscoverFunc) LocalInformerOption {
+ return func(informer *LocalInformer) {
+ informer.discover = discover
+ }
+}
+
+func NewLocalInformer(node Node, federation string, opts ...LocalInformerOption) (*LocalInformer, error) {
+ if node == nil || node.Host() == nil {
+ return nil, fmt.Errorf("node host is required")
+ }
+ emitter, err := node.Host().EventBus().Emitter(new(AgentWatchEvent))
+ if err != nil {
+ return nil, fmt.Errorf("creating agent event emitter: %w", err)
+ }
+ informer := &LocalInformer{
+ node: node,
+ federation: strings.TrimSpace(federation),
+ interval: defaultInformerPeriod,
+ emitter: emitter,
+ knownByID: map[string]string{},
+ }
+ for _, opt := range opts {
+ opt(informer)
+ }
+ if informer.interval <= 0 {
+ informer.interval = defaultInformerPeriod
+ }
+ if informer.discover == nil {
+ return nil, fmt.Errorf("informer discoverer is required")
+ }
+ cached, err := LoadCachedAgentRecords(informer.federation)
+ if err != nil {
+ return nil, err
+ }
+ for _, record := range cached {
+ if strings.TrimSpace(record.PeerID) == "" {
+ continue
+ }
+ informer.knownByID[record.PeerID] = informer.fingerprint(record.PeerID, record.Card)
+ }
+ return informer, nil
+}
+
+func (i *LocalInformer) Start(ctx context.Context) {
+ go func() {
+ _ = i.Sync(ctx)
+ ticker := time.NewTicker(i.interval)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ return
+ case <-ticker.C:
+ _ = i.Sync(ctx)
+ }
+ }
+ }()
+}
+
+func (i *LocalInformer) Sync(ctx context.Context) error {
+ records, err := i.discover(ctx)
+ if err != nil {
+ return err
+ }
+ for _, record := range records {
+ if err := UpsertCachedAgentRecord(i.federation, record); err != nil {
+ continue
+ }
+ if i.markSeen(record) {
+ _ = i.emitter.Emit(AgentWatchEvent{Type: AgentWatchEventAdded, PeerID: record.PeerID, Card: append([]byte(nil), record.Card...)})
+ }
+ }
+ return nil
+}
+
+func (i *LocalInformer) markSeen(record DiscoveredAgent) bool {
+ fingerprint := i.fingerprint(record.PeerID, record.Card)
+ i.mu.Lock()
+ defer i.mu.Unlock()
+ if known, ok := i.knownByID[record.PeerID]; ok && known == fingerprint {
+ return false
+ }
+ i.knownByID[record.PeerID] = fingerprint
+ return true
+}
+
+func (i *LocalInformer) fingerprint(peerID string, card []byte) string {
+ return strings.TrimSpace(peerID) + "|" + string(card)
+}
+
+type CachedAgentRecord struct {
+ PeerID string `json:"peer_id"`
+ Card json.RawMessage `json:"card"`
+ Capabilities []string `json:"capabilities,omitempty"`
+}
+
+func LoadCachedAgentRecords(federation string) ([]CachedAgentRecord, error) {
+ path, err := federationDBPath(federation)
+ if err != nil {
+ return nil, err
+ }
+ if _, err := os.Stat(path); err != nil {
+ if os.IsNotExist(err) {
+ return nil, nil
+ }
+ return nil, err
+ }
+ db, err := bbolt.Open(path, 0o600, &bbolt.Options{Timeout: 2 * time.Second, ReadOnly: true})
+ if err != nil {
+ return nil, err
+ }
+ defer func() { _ = db.Close() }()
+
+ codec := internaldb.JSONCodec{}
+ seen := map[string]struct{}{}
+ out := make([]CachedAgentRecord, 0)
+ err = db.View(func(tx *bbolt.Tx) error {
+ bucket := tx.Bucket([]byte(internaldb.BucketCache))
+ if bucket == nil {
+ return nil
+ }
+ return bucket.ForEach(func(key, value []byte) error {
+ if !strings.HasPrefix(string(key), agentCacheCardPrefix) {
+ return nil
+ }
+ var record CachedAgentRecord
+ if err := codec.Unmarshal(value, agentCacheRecordVersion, &record, nil); err != nil {
+ return nil
+ }
+ if strings.TrimSpace(record.PeerID) == "" {
+ return nil
+ }
+ if _, ok := seen[record.PeerID]; ok {
+ return nil
+ }
+ seen[record.PeerID] = struct{}{}
+ out = append(out, record)
+ return nil
+ })
+ })
+ if err != nil {
+ return nil, err
+ }
+ return out, nil
+}
+
+func CachedCapabilities(federation string) ([]string, error) {
+ records, err := LoadCachedAgentRecords(federation)
+ if err != nil {
+ return nil, err
+ }
+ seen := map[string]struct{}{}
+ out := make([]string, 0)
+ for _, record := range records {
+ for _, capability := range record.Capabilities {
+ capability = strings.TrimSpace(capability)
+ if capability == "" {
+ continue
+ }
+ if _, ok := seen[capability]; ok {
+ continue
+ }
+ seen[capability] = struct{}{}
+ out = append(out, capability)
+ }
+ }
+ return out, nil
+}
+
+func UpsertCachedAgentRecord(federation string, record DiscoveredAgent) error {
+ if strings.TrimSpace(record.PeerID) == "" || len(record.Card) == 0 {
+ return nil
+ }
+ path, err := federationDBPath(federation)
+ if err != nil {
+ return err
+ }
+ db, err := bbolt.Open(path, 0o600, &bbolt.Options{Timeout: 2 * time.Second})
+ if err != nil {
+ return err
+ }
+ defer func() { _ = db.Close() }()
+
+ codec := internaldb.JSONCodec{}
+ payload, err := codec.Marshal(agentCacheRecordVersion, CachedAgentRecord{
+ PeerID: record.PeerID,
+ Card: append([]byte(nil), record.Card...),
+ Capabilities: append([]string(nil), record.Capabilities...),
+ })
+ if err != nil {
+ return err
+ }
+ return db.Update(func(tx *bbolt.Tx) error {
+ bucket, err := tx.CreateBucketIfNotExists([]byte(internaldb.BucketCache))
+ if err != nil {
+ return fmt.Errorf("ensuring cache bucket: %w", err)
+ }
+ return bucket.Put([]byte(agentCacheCardPrefix+record.PeerID), payload)
+ })
+}
+
+func federationDBPath(federation string) (string, error) {
+ baseDir, err := internaldb.FederationsDir()
+ if err != nil {
+ return "", err
+ }
+ name := strings.TrimSpace(federation)
+ if name == "" {
+ name = "default"
+ }
+ if err := os.MkdirAll(baseDir, 0o700); err != nil {
+ return "", err
+ }
+ return filepath.Join(baseDir, name+".db"), nil
+}
diff --git a/tests/e2e/watch.bats b/tests/e2e/watch.bats
new file mode 100644
index 00000000..fe694863
--- /dev/null
+++ b/tests/e2e/watch.bats
@@ -0,0 +1,67 @@
+#!/usr/bin/env bats
+
+setup() {
+ export SAM_BINARY="${SAM_BINARY:-./bin/sam}"
+ if [[ ! -x "$SAM_BINARY" ]]; then
+ skip "sam binary not found at $SAM_BINARY"
+ fi
+
+ export TEST_TMPDIR
+ TEST_TMPDIR="$(mktemp -d)"
+ export HOME="$TEST_TMPDIR/home"
+ export XDG_CONFIG_HOME="$HOME/.config"
+ mkdir -p "$XDG_CONFIG_HOME"
+}
+
+teardown() {
+ rm -rf "$TEST_TMPDIR"
+}
+
+@test "sam mesh get agents --watch updates when a new agent is published" {
+ watcher_log="$TEST_TMPDIR/mesh-watch.log"
+ publisher_log="$TEST_TMPDIR/mesh-publisher.log"
+ watcher_listen="/ip4/127.0.0.1/udp/4320/quic-v1"
+ publisher_listen="/ip4/127.0.0.1/udp/4321/quic-v1"
+
+ "$SAM_BINARY" mesh get agents --watch -o json --listen "$watcher_listen" --dht-mode server --run-for 20s >"$watcher_log" 2>&1 &
+ watcher_pid=$!
+
+ watcher_peer=""
+ for _ in {1..100}; do
+ watcher_peer="$(grep -o 'peer_id=[^ ]*' "$watcher_log" | head -n1 | cut -d= -f2)"
+ if [[ -n "$watcher_peer" ]]; then
+ break
+ fi
+ sleep 0.1
+ done
+ [[ -n "$watcher_peer" ]]
+
+ "$SAM_BINARY" publish --skill writer --mcp-port 19100 --listen "$publisher_listen" --bootstrap "/ip4/127.0.0.1/udp/4320/quic-v1/p2p/${watcher_peer}" --dht-mode server --run-for 8s >"$publisher_log" 2>&1 &
+ publisher_pid=$!
+
+ publisher_peer=""
+ for _ in {1..100}; do
+ publisher_peer="$(grep -o 'peer_id=[^ ]*' "$publisher_log" | head -n1 | cut -d= -f2)"
+ if [[ -n "$publisher_peer" ]]; then
+ break
+ fi
+ sleep 0.1
+ done
+ [[ -n "$publisher_peer" ]]
+
+ found=""
+ for _ in {1..120}; do
+ if grep -q "\"peer_id\":\"$publisher_peer\"" "$watcher_log" && grep -q 'writer' "$watcher_log"; then
+ found="yes"
+ break
+ fi
+ sleep 0.2
+ done
+
+ kill "$publisher_pid" >/dev/null 2>&1 || true
+ wait "$publisher_pid" >/dev/null 2>&1 || true
+ kill "$watcher_pid" >/dev/null 2>&1 || true
+ wait "$watcher_pid" >/dev/null 2>&1 || true
+
+ [[ "$found" == "yes" ]]
+}
\ No newline at end of file