feat(graph): Act() on Graph interface + CompositeGraph multiplexer (#49)

* feat(graph): add Act() to Graph interface and CompositeGraph multiplexer

Extends the Graph interface with Act(id, action, payload) for interactive
graphs (browser DOM, terminal sessions, macOS AX elements). Passive graphs
(MemoryStore, SQLiteGraph, WritableGraph) return ErrActNotSupported.

CompositeGraph routes path prefixes to mounted sub-graphs, enabling
multi-source filesystems (/browser/, /iterm/, /macos/) through a single
Graph interface. The Navigator's ActTool delegates to engine.Act() with
zero knowledge of mount points.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(graph): re-prefix paths in CompositeGraph to maintain namespace isolation

Sub-graph methods (GetNode, ListChildren, GetCallers, GetCallees, Act)
returned paths relative to the sub-graph. Callers seeing "header/nav"
instead of "browser/header/nav" would fail on subsequent lookups. Add
reprefixNode helper and fix all delegation methods to return globally
valid composite paths. Also fix Act's HasPrefix check to use prefix+"/"
avoiding false matches like "app" matching "application/...".

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jamestexas

graph/graph.go

@@ -35,8 +35,21 @@ type CallExtractor = ig.CallExtractor
 // QualifiedCall represents a function call with optional package qualifier.
 type QualifiedCall = ig.QualifiedCall
 
+// CompositeGraph multiplexes multiple Graph backends under path prefixes.
+// Mount "browser" → /browser/... routes to that sub-graph.
+type CompositeGraph = ig.CompositeGraph
+
+// ActionResult is returned when an action is performed on a graph node.
+type ActionResult = ig.ActionResult
+
 // NewMemoryStore creates a new in-memory graph store.
 var NewMemoryStore = ig.NewMemoryStore
 
+// NewCompositeGraph creates an empty composite graph for multi-mount routing.
+var NewCompositeGraph = ig.NewCompositeGraph
+
 // ErrNotFound is returned when a node ID does not exist in the graph.
 var ErrNotFound = ig.ErrNotFound
+
+// ErrActNotSupported is returned by Graph implementations that do not support actions.
+var ErrActNotSupported = ig.ErrActNotSupported

internal/graph/composite.go

@@ -0,0 +1,233 @@
+package graph
+
+import (
+	"fmt"
+	"io/fs"
+	"strings"
+	"sync"
+	"time"
+)
+
+// CompositeGraph multiplexes multiple Graph backends under path prefixes.
+// Mount "browser" → paths under /browser/ route to that sub-graph.
+// Mount "iterm"   → paths under /iterm/ route to that sub-graph.
+// Root ListChildren returns the list of mount point names.
+type CompositeGraph struct {
+	mu     sync.RWMutex
+	mounts map[string]Graph // prefix → sub-graph
+}
+
+// NewCompositeGraph creates an empty composite graph.
+func NewCompositeGraph() *CompositeGraph {
+	return &CompositeGraph{mounts: make(map[string]Graph)}
+}
+
+// Mount registers a sub-graph under the given prefix.
+// Paths like "/<prefix>/..." are routed to this graph with the prefix stripped.
+func (c *CompositeGraph) Mount(prefix string, g Graph) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if _, ok := c.mounts[prefix]; ok {
+		return fmt.Errorf("mount %q already exists", prefix)
+	}
+	c.mounts[prefix] = g
+	return nil
+}
+
+// Unmount removes a previously mounted sub-graph.
+func (c *CompositeGraph) Unmount(prefix string) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if _, ok := c.mounts[prefix]; !ok {
+		return fmt.Errorf("mount %q not found", prefix)
+	}
+	delete(c.mounts, prefix)
+	return nil
+}
+
+// resolve splits id into (prefix, sub-path, sub-graph).
+// Returns ("", "", nil) if no mount matches.
+func (c *CompositeGraph) resolve(id string) (string, string, Graph) {
+	id = strings.TrimPrefix(id, "/")
+	if id == "" {
+		return "", "", nil
+	}
+	prefix, subPath, _ := strings.Cut(id, "/")
+	g, ok := c.mounts[prefix]
+	if !ok {
+		return "", "", nil
+	}
+	return prefix, subPath, g
+}
+
+// GetNode implements Graph.
+func (c *CompositeGraph) GetNode(id string) (*Node, error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	id = strings.TrimPrefix(id, "/")
+	if id == "" {
+		return &Node{
+			ID:      "",
+			Mode:    fs.ModeDir | 0o555,
+			ModTime: time.Now(),
+		}, nil
+	}
+
+	prefix, subPath, g := c.resolve(id)
+	if g == nil {
+		return nil, ErrNotFound
+	}
+	// Mount point directory itself (e.g., "browser" with no sub-path)
+	if subPath == "" {
+		return &Node{
+			ID:      id,
+			Mode:    fs.ModeDir | 0o555,
+			ModTime: time.Now(),
+		}, nil
+	}
+	n, err := g.GetNode(subPath)
+	if err != nil {
+		return nil, err
+	}
+	return c.reprefixNode(prefix, n), nil
+}
+
+// ListChildren implements Graph.
+func (c *CompositeGraph) ListChildren(id string) ([]string, error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	id = strings.TrimPrefix(id, "/")
+
+	// Root: return mount point names
+	if id == "" {
+		names := make([]string, 0, len(c.mounts))
+		for prefix := range c.mounts {
+			names = append(names, prefix)
+		}
+		return names, nil
+	}
+
+	prefix, subPath, g := c.resolve(id)
+	if g == nil {
+		return nil, ErrNotFound
+	}
+	var children []string
+	var err error
+	if subPath == "" {
+		children, err = g.ListChildren("")
+	} else {
+		children, err = g.ListChildren(subPath)
+	}
+	if err != nil {
+		return nil, err
+	}
+	res := make([]string, len(children))
+	for i, child := range children {
+		res[i] = prefix + "/" + strings.TrimPrefix(child, "/")
+	}
+	return res, nil
+}
+
+// ReadContent implements Graph.
+func (c *CompositeGraph) ReadContent(id string, buf []byte, offset int64) (int, error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	_, subPath, g := c.resolve(id)
+	if g == nil {
+		return 0, ErrNotFound
+	}
+	return g.ReadContent(subPath, buf, offset)
+}
+
+// GetCallers implements Graph. Searches all mounted sub-graphs.
+func (c *CompositeGraph) GetCallers(token string) ([]*Node, error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	var all []*Node
+	for prefix, g := range c.mounts {
+		nodes, err := g.GetCallers(token)
+		if err != nil {
+			continue
+		}
+		for _, n := range nodes {
+			all = append(all, c.reprefixNode(prefix, n))
+		}
+	}
+	return all, nil
+}
+
+// GetCallees implements Graph.
+func (c *CompositeGraph) GetCallees(id string) ([]*Node, error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	prefix, subPath, g := c.resolve(id)
+	if g == nil {
+		return nil, ErrNotFound
+	}
+	nodes, err := g.GetCallees(subPath)
+	if err != nil {
+		return nil, err
+	}
+	res := make([]*Node, len(nodes))
+	for i, n := range nodes {
+		res[i] = c.reprefixNode(prefix, n)
+	}
+	return res, nil
+}
+
+// Invalidate implements Graph.
+func (c *CompositeGraph) Invalidate(id string) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	_, subPath, g := c.resolve(id)
+	if g != nil {
+		g.Invalidate(subPath)
+	}
+}
+
+// Act implements Graph. Routes to the appropriate sub-graph.
+func (c *CompositeGraph) Act(id, action, payload string) (*ActionResult, error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	prefix, subPath, g := c.resolve(id)
+	if g == nil {
+		return nil, ErrNotFound
+	}
+	result, err := g.Act(subPath, action, payload)
+	if err != nil {
+		return nil, err
+	}
+	// Re-prefix paths in the result so the caller sees full composite paths
+	if result != nil {
+		if result.Path != "" && !strings.HasPrefix(result.Path, prefix+"/") {
+			result.Path = prefix + "/" + strings.TrimPrefix(result.Path, "/")
+		}
+		if result.NodeID != "" && !strings.HasPrefix(result.NodeID, prefix+"/") {
+			result.NodeID = prefix + "/" + strings.TrimPrefix(result.NodeID, "/")
+		}
+	}
+	return result, nil
+}
+
+// reprefixNode returns a shallow copy of n with ID and Children prefixed by the mount point.
+func (c *CompositeGraph) reprefixNode(prefix string, n *Node) *Node {
+	nCopy := *n
+	nCopy.ID = prefix + "/" + nCopy.ID
+	if len(nCopy.Children) > 0 {
+		nCopy.Children = make([]string, len(n.Children))
+		for i, child := range n.Children {
+			nCopy.Children[i] = prefix + "/" + child
+		}
+	}
+	return &nCopy
+}
+
+// Verify interface compliance at compile time.
+var _ Graph = (*CompositeGraph)(nil)