feat(gateway): add MediaSender/CapabilityReporter and TurnStream.Media

Channels had no shared contract for delivering non-text tool output --
MessageEvent/MediaAttachment/MsgVideo existed but nothing produced or
consumed them. MediaSender and CapabilityReporter give a channel an
optional, capability-queryable way to deliver an attachment; TurnStream
gains Media(event) alongside Delta/ToolCall so a tool's media reaches
the channel in the same ordered pass as its text.

CapabilitiesOf takes any deliberately: it must not depend on the
soon-to-be-removed BasePlatformAdapter (archie-core-azbo), since the
live channels implement channels.Channel, not that interface.
This commit is contained in:
sam committed 2026-08-23 02:47:53 +10:00
1 parent 925719a962
commit 242ae53fdf
5 files changed
+200

No files matched your search

+49
View File
@@ -0,0 +1,49 @@
package gateway
import "context"
// AdapterCapabilities reports which optional BasePlatformAdapter behaviors
// an adapter implements, so callers can check support before attempting an
// optional call rather than discovering it via a failed type assertion or a
// runtime error.
type AdapterCapabilities struct {
// Media is true when the adapter implements MediaSender.
Media bool
}
// MediaSender is the optional interface a BasePlatformAdapter implements
// when it can deliver a MessageEvent carrying MediaAttachments (image,
// video, audio, document) through a platform-specific media API distinct
// from plain-text Send -- e.g. Telegram's SendPhoto/SendVideo versus
// SendMessage.
type MediaSender interface {
SendMedia(ctx context.Context, event MessageEvent) (SendResult, error)
}
// CapabilityReporter is the optional interface an adapter implements to
// self-report which optional behaviors it supports. Callers should go
// through CapabilitiesOf rather than type-asserting this directly, so an
// adapter that implements MediaSender but forgets CapabilityReporter still
// reports correctly.
type CapabilityReporter interface {
Capabilities() AdapterCapabilities
}
// CapabilitiesOf reports which optional behaviors sender supports. One that
// implements CapabilityReporter is asked directly; one that doesn't is
// treated as reporting the zero value regardless of which optional
// interfaces it actually implements under the hood, which is itself the
// contract every Capabilities() implementation must honor -- see the
// regression coverage in adapter_capabilities_test.go.
//
// It takes any rather than BasePlatformAdapter deliberately: the live
// channels (telegram, email, webhook) implement channels.Channel, not
// BasePlatformAdapter, and media is delivered by launch-scoped sender
// values that are neither. Binding this helper to BasePlatformAdapter
// would tie it to a type slated for removal (archie-core-azbo).
func CapabilitiesOf(sender any) AdapterCapabilities {
if reporter, ok := sender.(CapabilityReporter); ok {
return reporter.Capabilities()
}
return AdapterCapabilities{}
}
@@ -0,0 +1,82 @@
package gateway
import (
"context"
"testing"
)
// mediaStubAdapter implements BasePlatformAdapter, MediaSender, and
// CapabilityReporter, reporting Media: true.
type mediaStubAdapter struct {
stubAdapter
}
func (s *mediaStubAdapter) SendMedia(ctx context.Context, e MessageEvent) (SendResult, error) {
return SendResult{Success: true, MessageID: "media-1"}, nil
}
func (s *mediaStubAdapter) Capabilities() AdapterCapabilities {
return AdapterCapabilities{Media: true}
}
var (
_ BasePlatformAdapter = (*mediaStubAdapter)(nil)
_ MediaSender = (*mediaStubAdapter)(nil)
_ CapabilityReporter = (*mediaStubAdapter)(nil)
)
func TestCapabilitiesOf_MatchesImplementedInterfaces(t *testing.T) {
tests := []struct {
name string
adapter any
wantMedia bool
implsMedia bool
}{
{
name: "adapter without media support",
adapter: &stubAdapter{},
wantMedia: false,
implsMedia: false,
},
{
name: "adapter with media support",
adapter: &mediaStubAdapter{},
wantMedia: true,
implsMedia: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
caps := CapabilitiesOf(tt.adapter)
if caps.Media != tt.wantMedia {
t.Errorf("CapabilitiesOf(%s).Media = %v, want %v", tt.name, caps.Media, tt.wantMedia)
}
_, implementsMediaSender := tt.adapter.(MediaSender)
if implementsMediaSender != tt.implsMedia {
t.Errorf("%s: MediaSender type assertion = %v, want %v", tt.name, implementsMediaSender, tt.implsMedia)
}
// The regression the acceptance criteria calls for: a claimed
// capability must match the actually-implemented interface.
if caps.Media != implementsMediaSender {
t.Errorf("%s: Capabilities().Media (%v) disagrees with MediaSender implementation (%v)", tt.name, caps.Media, implementsMediaSender)
}
})
}
}
func TestMediaSender_SendMedia(t *testing.T) {
a := &mediaStubAdapter{}
sr, err := a.SendMedia(context.Background(), MessageEvent{
Type: MsgVideo,
Media: []MediaAttachment{{Type: "video", URL: "https://example.com/v.mp4"}},
})
if err != nil {
t.Fatalf("SendMedia: %v", err)
}
if !sr.Success {
t.Error("expected SendMedia to succeed")
}
}
+28
View File
@@ -115,6 +115,16 @@ func truncateRunesWithinLimit(s string, limit int) string {
return string(runes[:limit-1]) + "…"
}
// MediaEvent reports one media attachment produced during a turn, so a
// channel can deliver it (e.g. through gateway.MediaSender) in the same
// ordered pass as the text and tool activity that surrounded it.
type MediaEvent struct {
// ToolName is the tool call that produced the attachment.
ToolName string
// Attachment is the media to deliver.
Attachment MediaAttachment
}
// TurnStream receives a turn's output as it is produced.
//
// It replaces the plain delta callback so a channel can render tool activity
@@ -129,6 +139,11 @@ type TurnStream interface {
Delta(text string)
// ToolCall reports a tool invocation that has finished executing.
ToolCall(event ToolCallEvent)
// Media reports a media attachment a tool call produced during the
// turn. A channel that cannot deliver it inline (see
// gateway.CapabilitiesOf) is expected to fall back to rendering the
// attachment's URL as text instead of dropping it silently.
Media(event MediaEvent)
}
// DeltaFunc adapts a plain text-delta callback to TurnStream for callers that
@@ -147,6 +162,9 @@ func (f DeltaFunc) Delta(text string) {
// ToolCall discards the event: a text-only caller has nowhere to put it.
func (f DeltaFunc) ToolCall(ToolCallEvent) {}
// Media discards the event: a text-only caller has nowhere to put it.
func (f DeltaFunc) Media(MediaEvent) {}
// toolCallRecorder wraps a TurnStream, forwarding every event to it
// unchanged while also recording the tool calls in arrival order. The
// recording happens regardless of whether next is nil (a non-streaming
@@ -174,6 +192,16 @@ func (r *toolCallRecorder) ToolCall(event ToolCallEvent) {
}
}
// Media forwards the event to the wrapped stream, if any. Unlike ToolCall,
// it is not recorded: media persistence and replay are not yet a supported
// path (see archie-core-1786748942243-6-f109697e), so recording it here
// would create a ledger field nothing reads.
func (r *toolCallRecorder) Media(event MediaEvent) {
if r.next != nil {
r.next.Media(event)
}
}
// firstNonEmptyLine returns the first line of s that holds something other
// than whitespace, trimmed. It returns "" when there is no such line.
func firstNonEmptyLine(s string) string {
+37
View File
@@ -127,4 +127,41 @@ func TestDeltaFuncNilIsInert(t *testing.T) {
stream := DeltaFunc(nil)
stream.Delta("anything")
stream.ToolCall(ToolCallEvent{Name: "shell"})
stream.Media(MediaEvent{ToolName: "video_gen"})
}
// A text-only caller has nowhere to put media, so DeltaFunc must discard it
// exactly like it discards ToolCall -- never panic, never route it into the
// text stream as a raw URL the caller didn't ask for.
func TestDeltaFuncDiscardsMedia(t *testing.T) {
var got []string
stream := DeltaFunc(func(delta string) { got = append(got, delta) })
stream.Media(MediaEvent{ToolName: "video_gen", Attachment: MediaAttachment{Type: "video", URL: "https://example.com/v.mp4"}})
if len(got) != 0 {
t.Fatalf("Media leaked into the text stream: %v", got)
}
}
// toolCallRecorder must forward Media to the wrapped stream unchanged, the
// same contract it already honors for Delta and ToolCall.
func TestToolCallRecorderForwardsMedia(t *testing.T) {
next := &recordingStream{}
r := &toolCallRecorder{next: next}
event := MediaEvent{ToolName: "video_gen", Attachment: MediaAttachment{Type: "video", URL: "https://example.com/v.mp4"}}
r.Media(event)
want := []string{"media:video_gen:video"}
if len(next.events) != len(want) || next.events[0] != want[0] {
t.Fatalf("events = %v, want %v", next.events, want)
}
}
// toolCallRecorder must not panic when wrapping a nil stream (the
// non-streaming caller case Delta/ToolCall already handle).
func TestToolCallRecorderMediaNilNextIsInert(t *testing.T) {
r := &toolCallRecorder{}
r.Media(MediaEvent{ToolName: "video_gen"})
}
+4
View File
@@ -20,6 +20,10 @@ func (s *recordingStream) ToolCall(event ToolCallEvent) {
s.events = append(s.events, "tool:"+event.Name+":"+event.Summary())
}
func (s *recordingStream) Media(event MediaEvent) {
s.events = append(s.events, "media:"+event.ToolName+":"+event.Attachment.Type)
}
func newStreamTestRunner(t *testing.T, prepared *turnTestPreparedModel) *TurnRunner {
t.Helper()
store := NewSessionStoreMemory()