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:
1 parent
925719a962
commit
242ae53fdf
5 files changed
+200
No files matched your search
@@ -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")
|
||||
}
|
||||
}
|
||||
@@ -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 {
|
||||
|
||||
@@ -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"})
|
||||
}
|
||||
@@ -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()
|
||||
|
||||
Reference in new issue
Block a user