feat(telemetry): emit per-app usage events from supervisor callFrom (PILOT-402) (#20)

After every IPC call through supervisor.callFrom (the single chokepoint
for CLI+daemon+cross-app dispatch), a telemetry usage event is emitted
with app_id, method, caller_id, ok status, duration, and optional error.

The supervisor accepts a TelemetryEmitter interface via Deps.Telemetry
and defaults to a no-op when no emitter is wired. The web4 daemon adapter
wraps the consent-gated telemetry.Client to emit app_usage events,
sharing the daemon's identity file and telemetry URL.

Closes PILOT-402

Co-authored-by: matthew-pilot <matthew@pilotprotocol.network>

Author: matthew-pilot

plugin/appstore/service.go

@@ -135,12 +135,13 @@ func (s *Service) Order() int { return 120 }
 // Go's structural typing makes this work as long as the methods used here
 // are present on the real types.
 type Deps struct {
-	Streams  any // coreapi.Streams — Dial, Listen, SendDatagram
-	Identity any // coreapi.Identity — NodeID, Address, PublicKey, Sign
-	Resolver any
-	Events   any // coreapi.EventBus — Publish, Subscribe
-	Logger   any
-	Trust    any
+	Streams    any // coreapi.Streams — Dial, Listen, SendDatagram
+	Identity   any // coreapi.Identity — NodeID, Address, PublicKey, Sign
+	Resolver   any
+	Events     any // coreapi.EventBus — Publish, Subscribe
+	Logger     any
+	Trust      any
+	Telemetry  TelemetryEmitter // optional; no-op when nil
 }
 
 // Start scans InstallRoot for installed apps, verifies each binary's

plugin/appstore/supervisor.go

@@ -171,6 +171,10 @@ type supervisor struct {
 }
 
 func newSupervisor(cfg Config, deps Deps, logger *log.Logger) *supervisor {
+	// Default no-op telemetry when the daemon doesn't wire one.
+	if deps.Telemetry == nil {
+		deps.Telemetry = noopEmitter{}
+	}
 	return &supervisor{
 		cfg:       cfg,
 		deps:      deps,
@@ -1035,36 +1039,49 @@ func (s *supervisor) CallFrom(ctx context.Context, callerID, appID, method strin
 // connection is dialed per-call — simple and lets the app's own
 // concurrency handle multiple in-flight calls. Returns the typed gate
 // errors above, or otherwise propagates the app's IPC response/error.
+//
+// After every call (success or failure) a telemetry usage event is
+// emitted — best-effort, never blocks the caller.
 func (s *supervisor) callFrom(ctx context.Context, callerID, appID, method string, args, out any) error {
 	s.mu.RLock()
 	app, ok := s.installed[appID]
 	caller, callerOK := s.installed[callerID]
 	ready := s.ready[appID]
 	s.mu.RUnlock()
 	if !ok {
-		return fmt.Errorf("%w: %s", ErrAppNotInstalled, appID)
+		err := fmt.Errorf("%w: %s", ErrAppNotInstalled, appID)
+		s.emitUsage(callerID, appID, method, false, 0, err.Error())
+		return err
 	}
 	// Broker-surface gate: only methods the app explicitly exposes are
 	// dispatchable, for every caller including the daemon itself.
 	if !app.Manifest.ExposesMethod(method) {
-		return fmt.Errorf("%w: %s.%s", ErrMethodNotExposed, appID, method)
+		err := fmt.Errorf("%w: %s.%s", ErrMethodNotExposed, appID, method)
+		s.emitUsage(callerID, appID, method, false, 0, err.Error())
+		return err
 	}
 	// Cross-app grant gate: a calling app must have declared an ipc.call
 	// grant targeting the specific method it wants to invoke. Trusted
 	// callers (empty callerID) skip this — they are the broker itself.
 	if callerID != "" {
 		if !callerOK {
-			return fmt.Errorf("%w: caller %q not installed", ErrGrantMissing, callerID)
+			err := fmt.Errorf("%w: caller %q not installed", ErrGrantMissing, callerID)
+			s.emitUsage(callerID, appID, method, false, 0, err.Error())
+			return err
 		}
 		target := appID + "." + method
 		if !caller.Manifest.HasGrant("ipc.call", target) {
-			return fmt.Errorf("%w: %s -> %s", ErrGrantMissing, callerID, target)
+			err := fmt.Errorf("%w: %s -> %s", ErrGrantMissing, callerID, target)
+			s.emitUsage(callerID, appID, method, false, 0, err.Error())
+			return err
 		}
 	}
 	if !ready {
 		// Give it a brief moment in case it just spawned.
 		if !s.awaitReady(ctx, appID, 1*time.Second) {
-			return fmt.Errorf("%w: %s", ErrAppNotReady, appID)
+			err := fmt.Errorf("%w: %s", ErrAppNotReady, appID)
+			s.emitUsage(callerID, appID, method, false, 0, err.Error())
+			return err
 		}
 	}
 
@@ -1082,7 +1099,39 @@ func (s *supervisor) callFrom(ctx context.Context, callerID, appID, method strin
 	if dl, ok := ctx.Deadline(); ok {
 		_ = conn.SetDeadline(dl)
 	}
-	return ipc.Call(conn, method, args, out)
+
+	start := time.Now()
+	err = ipc.Call(conn, method, args, out)
+	dur := time.Since(start).Milliseconds()
+	if err != nil {
+		s.emitUsage(callerID, appID, method, false, dur, err.Error())
+	} else {
+		s.emitUsage(callerID, appID, method, true, dur, "")
+	}
+	return err
+}
+
+// emitUsage best-effort fires a telemetry event into the Deps.Telemetry
+// emitter. It never blocks and recovers from emitter panics so a buggy
+// downstream never sinks the supervisor call path.
+func (s *supervisor) emitUsage(callerID, appID, method string, ok bool, durMs int64, errMsg string) {
+	t := s.deps.Telemetry
+	if t == nil {
+		return
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			s.logger.Printf("telemetry emitter panicked: %v", r)
+		}
+	}()
+	t.Emit(TelemetryEvent{
+		AppID:    appID,
+		Method:   method,
+		CallerID: callerID,
+		OK:       ok,
+		DurMs:    durMs,
+		ErrMsg:   errMsg,
+	})
 }
 
 // awaitReady polls the ready bit for app until it flips true or the

plugin/appstore/telemetry.go

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+package appstore
+
+// TelemetryEvent captures one app-usage event that the supervisor emits
+// after every successful (or failed) IPC call through callFrom. The
+// daemon's telemetry client converts these to signed HTTP POSTs.
+//
+// Fields match what the telemetry endpoint expects for "app_usage" kind
+// events. CallerID is empty for trusted daemon/pilotctl calls and
+// non-empty for cross-app calls.
+type TelemetryEvent struct {
+	AppID    string `json:"app_id"`
+	Method   string `json:"method"`
+	CallerID string `json:"caller_id,omitempty"`
+	OK       bool   `json:"ok"`
+	DurMs    int64  `json:"dur_ms"`
+	ErrMsg   string `json:"err_msg,omitempty"`
+}
+
+// TelemetryEmitter is the interface the supervisor calls to emit a usage
+// event. The daemon wires a real implementation; the no-op default is set
+// in newSupervisor so the supervisor never has to nil-check.
+type TelemetryEmitter interface {
+	Emit(event TelemetryEvent)
+}
+
+// noopEmitter discards every event. Used as the default when Deps does
+// not provide a Telemetry field, and also when consent is off.
+type noopEmitter struct{}
+
+func (noopEmitter) Emit(TelemetryEvent) {}