diff --git a/internal/gateway/adapter_capabilities.go b/internal/gateway/adapter_capabilities.go new file mode 100644 index 000000000..6d216c5cd --- /dev/null +++ b/internal/gateway/adapter_capabilities.go @@ -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{} +} diff --git a/internal/gateway/adapter_capabilities_test.go b/internal/gateway/adapter_capabilities_test.go new file mode 100644 index 000000000..b85f18212 --- /dev/null +++ b/internal/gateway/adapter_capabilities_test.go @@ -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") + } +} diff --git a/internal/gateway/stream.go b/internal/gateway/stream.go index d8b31244f..d2473d706 100644 --- a/internal/gateway/stream.go +++ b/internal/gateway/stream.go @@ -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 { diff --git a/internal/gateway/stream_test.go b/internal/gateway/stream_test.go index 0483d4b71..c2ba90c72 100644 --- a/internal/gateway/stream_test.go +++ b/internal/gateway/stream_test.go @@ -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"}) } diff --git a/internal/gateway/turn_stream_test.go b/internal/gateway/turn_stream_test.go index c75f0b574..de35e444e 100644 --- a/internal/gateway/turn_stream_test.go +++ b/internal/gateway/turn_stream_test.go @@ -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()