feat(session): Plugin invocation contract + 5-value action vocabulary + abctl row-per-plugin renderer

[huang195]

Summary

Closes the observability gap where auth decisions and per-plugin actions were invisible in /v1/sessions and abctl. Introduces a unified plugin-invocation contract that every plugin emits, a 5-value action vocabulary shared across gate and parser plugins, a SessionDenied phase for rejected requests, and a rewritten abctl event pane that renders one row per plugin invocation with clear request↔response pairing.

New wire-schema

Every event on /v1/sessions/{id} and /v1/events carries an invocations field — a per-plugin record of what each plugin did during the pipeline pass:

{
  "phase": "request" | "response" | "denied",
  "invocations": {
    "inbound": [
      {
        "plugin": "jwt-validation",
        "action": "allow",
        "phase": "request",
        "reason": "authorized",
        "path": "/message/stream",
        "tokenSubject": "alice",
        "tokenAudience": ["..."],
        "tokenScopes": ["openid", "..."]
      }
    ],
    "outbound": [
      {
        "plugin": "token-exchange",
        "action": "modify",
        "phase": "request",
        "reason": "token_replaced",
        "routeMatched": true,
        "routeHost": "weather-tool-mcp",
        "targetAudience": "spiffe://...",
        "cacheHit": false
      }
    ]
  }
}

5-value action vocabulary

Every plugin MUST emit exactly one of these per invocation:

Action	Meaning	Example
allow	Gate plugin permitted the request	jwt-validation on valid token
deny	Gate plugin rejected the request; pipeline stops	jwt-validation on bad token
skip	Plugin ran but didn't act on this message	jwt-validation bypass path
modify	Plugin mutated the message	token-exchange replaced the Authorization header
observe	Plugin attached diagnostic data without altering flow	parsers extracting MCP/A2A/Inference state

Reason codes discriminate within an action value (skip/path_bypass vs skip/no_matching_route) for finer-grained filtering.

What is new in abctl

• One row per plugin invocation. An event with N plugins produces N visually-linked rows.
• ACTION column renders the 5-value vocab. Filter /allow, /deny, /skip, /modify, /observe.
• Leftmost # column gives each event an integer ID; paired req/resp events share one number. Method-aware pairing so notifications/initialized doesn't steal the tools/list response.
• Continuation rows blank TIME/DIR/PHASE/STATUS/DURATION/HOST/# when they share an event with the row above — event reads as one visual block.
• SessionDenied events render with PHASE=denied carrying full diagnostic context.

Backward compatibility

Breaking for pre-existing consumers of the session wire format. SessionEvent.Auth -> SessionEvent.Invocations, and InboundAuth.Decision / OutboundAuth.Action (free-form strings) unify into Invocation.Action (5-value typed enum). Session API has no persistent state, so no migration needed. No operator or chart changes.

Test plan

• go test ./... in authlib, cmd/authbridge, cmd/abctl — all green
• go vet ./... across all three modules — clean
• Manual: rebuilt authbridge-envoy image, deployed to Kind, drove A2A + MCP + inference traffic; verified one-row-per-plugin rendering, pair IDs, SSE response bodies, filters

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

[pdettori]

Clean, well-structured PR with excellent test coverage across all layers (pipeline types, plugins, listener, session API, TUI). The 5-value action vocabulary is a well-designed abstraction that unifies gate and parser plugins without over-generalizing.

The pipeline executes plugins sequentially so the lazy-init pattern in appendInvocationInbound/Outbound is safe. Recording gates are correctly scoped and well-documented. No security issues found.

Areas reviewed: Go (pipeline types, 5 plugins, listener, session API, TUI), Docs (CONVENTIONS.md, CLAUDE.md)
Commits: 21 commits, all signed-off
CI status: All checks passing

Minor nit: PR title is 93 chars (convention is <72). Consider shortening for git log readability, e.g. feat(session): Plugin invocation contract + 5-value action vocabulary

[pdettori]

nit: CacheHit bool with omitempty means cache-miss (false) is omitted from JSON, making it indistinguishable from "field not applicable." Consumers can't filter cache misses without also knowing the action is modify. Fine for now — just noting the tradeoff. If you ever want an explicit cacheHit: false signal for perf dashboards, this would need *bool or a tristate.