feat(authlib): Add ContentSource capability for guardrail plugins

[huang195]

Summary

Adds a small capability interface so parser plugins can expose their inspectable text to guardrail plugins (PII scrubbers, jailbreak detectors, content classifiers, prompt-injection filters, etc.) without the guardrails having to import any specific parser package.

Today, a guardrail that wants to scan user-provided text has to branch on every protocol it might encounter:

if pctx.Extensions.Inference != nil { /* walk Messages, Completion, ToolCalls */ }
if pctx.Extensions.A2A != nil        { /* walk Parts, normalize role */ }
if pctx.Extensions.MCP != nil        { /* dig into Params["arguments"] map */ }

With this PR:

for _, src := range pctx.ContentSources() {
    for _, f := range src.Fragments() {
        if f.Role == contracts.RoleUser {
            scan(f.Text)
        }
    }
}

What's in it

New package authlib/contracts/ — dependency-free, defines:

type ContentSource interface {
    Fragments() []Fragment
}

type Fragment struct {
    Role string
    Text string
}

Plus standard role constants (RoleUser, RoleAssistant, RoleSystem, RoleTool, RoleToolArgs, RoleToolResult). Vocabulary is open — protocols that don't fit any value may emit their own role strings.

Fragments() implementations on existing extensions (authlib/pipeline/content.go), with compile-time assertions:

Extension	Request-phase output	Response-phase output
A2AExtension	text/data parts tagged with message role (agent → assistant); file parts skipped	artifact as assistant
MCPExtension	tools/call name as tool; each argument value as tool_args (JSON-stringified); control-plane RPCs return nil	result content[] text items as tool_result
InferenceExtension	messages keyed by role (tool → tool_result)	completion as assistant; tool calls emit name + args

Consumer helper — pctx.ContentSources() walks Extensions.A2A / .MCP / .Inference and returns non-nil ones satisfying the interface. Forward-compatible: when a protocols-registry refactor lands, the body rewrites to iterate a map — callers don't notice.

Docs — plugin-reference.md gets a new "Exposing content to guardrails" section with the role-mapping table, a consumer example, and guidance on when NOT to implement (structure-oriented guardrails). plugin-tutorial.md gets Step 8 showing the ~10-line opt-in. framework-architecture.md §4 cross-references.

What's NOT in it

• No wire-format change. Fragments() is a Go method; JSON marshalling is unaffected.
• No behavioral change for pipelines without guardrail plugins.
• No abctl changes. cmd/abctl builds and tests unchanged — the method is available on the decoded Go types automatically.
• No registry migration. Named slots stay put. This PR is useful regardless of whether the protocols-registry refactor ever lands.
• No guardrail plugin yet. This PR adds the contract and producer side only. Guardrail plugins arrive in follow-ups.

Test plan

• go build ./... in authlib, cmd/authbridge, cmd/abctl under GOWORK=off
• go test -race ./... passes in all three modules
• go vet ./... clean in all three modules
• gofmt -l clean on all files touched by this PR
• Table-driven tests cover: role normalization (A2A agent → assistant, Inference tool → tool_result), empty/nil edge cases, non-string argument JSON-stringification, control-plane RPC skip, ContentSources() enumeration and uniform iteration

Scope for follow-ups

• A reference guardrail plugin demonstrating the consumption pattern end-to-end.
• Optional Path field on Fragment for violation-report citations (deferred — current shape covers the 80% content-scanning case).
• MutableContentSource for inline redaction (deferred — depends on chained-mutator work).

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

[huang195]

Addressing review feedback in 548bd10. Five small fixes:

1. InferenceExtension.Fragments: use var out []Fragment for nil-when-empty consistency with A2A/MCP implementations.
2. stringifyAny: DEBUG log on marshal error + JSON-origin precondition in docstring.
3. normalizeA2ARole: rewrote the comment — interface consumers can't reach .Role without type-asserting back to the concrete type, so the original "raw value escape hatch" wording was misleading.
4. Fragment struct: added a forward-compat note recommending named-field initialization for when fields are added (e.g., Path for violation citations).
5. Tutorial Step 8: half-sentence pointer to A2AExtension.Fragments as the role-normalization reference.

On review comment #5 (merge-order coordination with #392): acknowledged — the rebase is trivial in either direction. If #392 lands first, the authlib/validation import gets dropped from this PR's pipeline/context.go hunk (leaving authlib/contracts alone). If this PR lands first, #392's context.go hunk keeps the authlib/contracts line alongside its own removals. No code change needed here.

[esnible]

I'm nervous about this type assertion and others. They skip invalid content. Perhaps if ok is false a counter should be updated, or a message logged, so developers have a way of seeing malicious non-MCP payloads?

[esnible]

MCP also has an isError field and errors can carry text. Should an error messages also be considered a fragment?

[huang195]

Rebased onto current main (PR #392 merged — conflict was the trivial 1-line hunk in pipeline/context.go imports that we flagged ahead of time).

Addressing the two inline reviews in a2e331b:

"skip invalid content silently" — Now logs at DEBUG on each unexpected-shape skip inside MCPExtension.Fragments:

• Params["arguments"] present but not map[string]any
• Result["content"] present but not []any
• Result.content[i] present but not a map

A full counter / metric would be heavier than the concern warrants — DEBUG is the right level for "operator debugging a weird client." If the project later adds structured metrics to the pipeline, wiring these counters in is additive.

"MCP errors can carry text — consider them fragments" — MCPError.Message is now emitted as a role=tool_result fragment when Err is non-nil and Message is non-empty. A PII scrubber, credential detector, or content classifier now covers the error channel uniformly with normal tool output — closes the gap you flagged. plugin-reference.md updated to note the tool_result role covers both result text and error messages.

5 new test cases cover: error-only, error-plus-result, empty-error-skip, malformed-arguments-skip, malformed-result-skip.