From c70b144782a77378c92771db7599c1916ba2f6b5 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 2 Oct 2026 10:15:50 +1000 Subject: [PATCH] fix(messaging): carry an inbound attachment's bytes to the gateway turn A Telegram photo or document was dropped between the process that receives it and the one that runs the turn. Telegram runs in archie-messaging, which downloads the attachment; the turn runs in archie-gateway/archied, which never holds the bot token. gatewayrpc stripped MediaAttachment.Data on the inbound request, so by the time the Gateway's model seam ran, the attachment had no bytes and no URL, and mediaParts dropped it -- the model read only the "[photo]" placeholder. - proto/gateway/v1: Media gains a `data` field, populated only on the inbound request. Stored-history and outbound-event directions keep it empty: a persisted record still strips the bytes, and a streamed media event still carries metadata only. - gatewayrpc: the inbound conversion maps Data; the stored and outbound conversions deliberately do not. - archied: the Gateway server raises its gRPC receive limit from the 4 MB default to the messaging contract's inbound attachment ceiling plus framing headroom, so a maximal (20 MB) attachment is accepted rather than failing the RPC. - messaging: MaxInboundAttachmentBytes is the single ceiling the Telegram download gate and the Gateway receive limit both derive from. Red first: a new TestInboundMediaBytesReachTheTurn asserted the bytes crossed the wire and failed at that assertion before the mapping changed; it was then consolidated into TestInboundMediaRoundTrip, which now pins metadata plus bytes. --- docs/data/generated/contracts.json | 2 +- internal/app/archied/gateway.go | 16 +++- internal/app/archied/gateway_test.go | 83 ++++++++++++++++++- internal/channels/telegram/inboundmedia.go | 5 +- internal/contracts/gateway/v1/chat.pb.go | 49 +++++++---- internal/domain/messaging/inbound.go | 11 ++- internal/domain/messaging/media.go | 16 +++- internal/infrastructure/gatewayrpc/values.go | 49 +++++++++-- .../gatewayrpc/values_media_test.go | 15 ++-- proto/gateway/v1/chat.proto | 13 ++- 10 files changed, 212 insertions(+), 47 deletions(-) diff --git a/docs/data/generated/contracts.json b/docs/data/generated/contracts.json index 8a359db66..e46e00278 100644 --- a/docs/data/generated/contracts.json +++ b/docs/data/generated/contracts.json @@ -314,7 +314,7 @@ "properties": { "data": { "contentEncoding": "base64", - "description": "Data carries the attachment bytes in-process. An inbound path sets\nit after downloading the file; outbound senders never set it and\nread Path or URL instead. It never crosses a wire or persistence\nboundary -- it is a turn-scoped value, not a stored one.", + "description": "Data carries the attachment bytes in-process. An inbound path sets\nit after downloading the file; outbound senders never set it and\nread Path or URL instead. It crosses the wire in one direction only:\nthe inbound request from a channel frontend to the Gateway process\nthat runs the turn, because that process never holds the platform\ncredential. It is never persisted, and the stored-history and\noutbound-event directions strip it.", "type": "string" }, "duration": { diff --git a/internal/app/archied/gateway.go b/internal/app/archied/gateway.go index e6faca138..cd3263582 100644 --- a/internal/app/archied/gateway.go +++ b/internal/app/archied/gateway.go @@ -12,6 +12,7 @@ import ( "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/applystatus" + "github.com/samcharles93/archie-core/internal/domain/messaging" "github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/gateway" "github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc" @@ -189,18 +190,30 @@ func (b *boot) startGatewayRuntime(ctx context.Context, actor gateway.ChatTaskAc return contract, nil } +// inboundMessageHeadroomBytes leaves room for the protobuf framing and the +// rest of the request around an attachment at the messaging contract's +// ceiling, so the largest attachment a channel frontend may send is accepted +// rather than rejected as an oversized gRPC message. +const inboundMessageHeadroomBytes = 1 << 20 + // gatewayServerOpts applies the transport security boundary: a loopback // listener is served insecure with no token; any non-loopback address // requires a Bearer [REDACTED], else the process fails closed. It mirrors // stateStoreServerOpts, minus the State Store's task-scoped grants: the // Gateway has one administrative token for all callers. +// +// The receive limit is raised above gRPC's 4 MB default because an inbound +// request carries a channel attachment's bytes: the channel frontend +// downloads the file, and this process -- which runs the turn -- holds no +// platform credential to fetch it again. func gatewayServerOpts(listen, token string) (opts []grpc.ServerOption, loopback bool, err error) { + recv := grpc.MaxRecvMsgSize(messaging.MaxInboundAttachmentBytes + inboundMessageHeadroomBytes) loopback, err = gatewayrpc.TargetIsLoopback(listen) if err != nil { return nil, false, err } if loopback { - return nil, true, nil + return []grpc.ServerOption{recv}, true, nil } if token == "" { return nil, false, fmt.Errorf( @@ -209,6 +222,7 @@ func gatewayServerOpts(listen, token string) (opts []grpc.ServerOption, loopback ) } return []grpc.ServerOption{ + recv, grpc.ChainUnaryInterceptor(gatewayrpc.UnaryServerInterceptor(token)), grpc.ChainStreamInterceptor(gatewayrpc.StreamServerInterceptor(token)), }, false, nil diff --git a/internal/app/archied/gateway_test.go b/internal/app/archied/gateway_test.go index 70789df9e..e9355b269 100644 --- a/internal/app/archied/gateway_test.go +++ b/internal/app/archied/gateway_test.go @@ -2,8 +2,11 @@ package archied import ( "context" + "errors" + "io" "log/slog" "net" + "sync" "testing" "time" @@ -25,8 +28,10 @@ func TestGatewayServerOptsLoopbackIsInsecure(t *testing.T) { if !loopback { t.Fatal("loopback listener should report loopback") } - if len(opts) != 0 { - t.Fatalf("loopback listener should have no server opts, got %d", len(opts)) + // Only the inbound size limit; a loopback listener installs no auth + // interceptors (the count is the only handle on opaque ServerOptions). + if len(opts) != 1 { + t.Fatalf("loopback listener should install only the inbound size limit, got %d options", len(opts)) } } @@ -41,8 +46,8 @@ func TestGatewayServerOptsNonLoopbackRequiresToken(t *testing.T) { if loopback { t.Fatal("non-loopback listener should not report loopback") } - if len(opts) != 2 { - t.Fatalf("non-loopback listener should install two server options (unary and stream auth interceptors), got %d", len(opts)) + if len(opts) != 3 { + t.Fatalf("non-loopback listener should install three server options (inbound size limit plus unary and stream auth interceptors), got %d", len(opts)) } } @@ -135,3 +140,73 @@ func TestGatewayServingAnnouncesReady(t *testing.T) { t.Fatalf("serveGatewayListener returned: %v", err) } } + +// recordingGatewayContract captures the inbound a Stream call reached the +// Gateway with, so a test can prove the request's payload survived the wire. +type recordingGatewayContract struct { + stubGatewayContract + mu sync.Mutex + last messaging.Inbound +} + +func (c *recordingGatewayContract) Stream(_ context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) { + c.mu.Lock() + c.last = in + c.mu.Unlock() + events := make(chan messaging.ChatEvent) + close(events) + return events, nil +} + +// TestGatewayAcceptsAnInboundAttachmentOverTheDefaultGRPCLimit: the inbound +// request now carries a channel attachment's bytes, and gRPC's default receive +// limit is 4 MB -- well under the messaging contract's ceiling. A maximal +// attachment must reach the turn, not fail the RPC with ResourceExhausted. +func TestGatewayAcceptsAnInboundAttachmentOverTheDefaultGRPCLimit(t *testing.T) { + rec := &recordingGatewayContract{} + ln, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0") + if err != nil { + t.Fatalf("listen: %v", err) + } + opts, _, err := gatewayServerOpts(ln.Addr().String(), "") + if err != nil { + t.Fatalf("gatewayServerOpts: %v", err) + } + ctx, cancel := context.WithCancel(t.Context()) + defer cancel() + serveCh := make(chan error, 1) + go func() { serveCh <- serveGateway(ctx, ln, rec, nil, opts) }() + defer func() { + cancel() + if err := <-serveCh; err != nil { + t.Errorf("serveGateway: %v", err) + } + }() + + conn, err := grpc.NewClient("passthrough:///"+ln.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials())) + if err != nil { + t.Fatalf("dial: %v", err) + } + defer conn.Close() + + raw := make([]byte, 5<<20) // larger than gRPC's 4 MB default receive limit + stream, err := pb.NewChatServiceClient(conn).Stream(t.Context(), &pb.StreamRequest{ + Message: &pb.Message{Media: []*pb.Media{{Type: "image", MimeType: "image/jpeg", Data: raw}}}, + }) + if err != nil { + t.Fatalf("Stream with a %d-byte attachment: %v", len(raw), err) + } + if _, err := stream.Recv(); !errors.Is(err, io.EOF) { + t.Fatalf("Recv after an empty stream: %v, want EOF", err) + } + + rec.mu.Lock() + got := rec.last + rec.mu.Unlock() + if len(got.Media) != 1 { + t.Fatalf("turn received %d attachments, want 1", len(got.Media)) + } + if len(got.Media[0].Data) != len(raw) { + t.Fatalf("turn received %d attachment bytes, want %d", len(got.Media[0].Data), len(raw)) + } +} diff --git a/internal/channels/telegram/inboundmedia.go b/internal/channels/telegram/inboundmedia.go index f6b1b3086..dc2dab4ea 100644 --- a/internal/channels/telegram/inboundmedia.go +++ b/internal/channels/telegram/inboundmedia.go @@ -117,8 +117,9 @@ func nilIfZero(v int64) *int64 { // maxInboundDownloadBytes is the Bot API download ceiling: bots cannot // fetch files larger than 20 MB through getFile, so a larger attachment // must be refused with a clear notice rather than met with a Bot API 400 -// nobody reads. -var maxInboundDownloadBytes int64 = 20 * 1024 * 1024 +// nobody reads. It is the messaging contract's inbound attachment ceiling, +// so the value the Gateway must be able to receive stays in one place. +var maxInboundDownloadBytes int64 = messaging.MaxInboundAttachmentBytes var errInboundMediaTooLarge = errors.New("file exceeds the bot download limit") diff --git a/internal/contracts/gateway/v1/chat.pb.go b/internal/contracts/gateway/v1/chat.pb.go index d74b44727..81632b137 100644 --- a/internal/contracts/gateway/v1/chat.pb.go +++ b/internal/contracts/gateway/v1/chat.pb.go @@ -163,9 +163,9 @@ type Message struct { // constant. Transport-only, never persisted: the session record keeps it. Platform string `protobuf:"bytes,10,opt,name=platform,proto3" json:"platform,omitempty"` // media carries attachment metadata for a message that arrived with a - // file. The attachment's bytes never cross this wire: a stored Media - // with tool_name empty is a sender attachment, and the tool_name on - // tool-produced events stays a stream-only field. + // file. The bytes ride only on the inbound request (see Media.data); a + // stored Media with tool_name empty is a sender attachment, and the + // tool_name on tool-produced events stays a stream-only field. Media []*Media `protobuf:"bytes,11,rep,name=media,proto3" json:"media,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -355,18 +355,25 @@ func (x *ToolCall) GetError() string { } type Media struct { - state protoimpl.MessageState `protogen:"open.v1"` - ToolName string `protobuf:"bytes,1,opt,name=tool_name,json=toolName,proto3" json:"tool_name,omitempty"` - Type string `protobuf:"bytes,2,opt,name=type,proto3" json:"type,omitempty"` - FileId string `protobuf:"bytes,3,opt,name=file_id,json=fileId,proto3" json:"file_id,omitempty"` - Url string `protobuf:"bytes,4,opt,name=url,proto3" json:"url,omitempty"` - Path string `protobuf:"bytes,5,opt,name=path,proto3" json:"path,omitempty"` - MimeType string `protobuf:"bytes,6,opt,name=mime_type,json=mimeType,proto3" json:"mime_type,omitempty"` - FileName string `protobuf:"bytes,7,opt,name=file_name,json=fileName,proto3" json:"file_name,omitempty"` - FileSize *int64 `protobuf:"varint,8,opt,name=file_size,json=fileSize,proto3,oneof" json:"file_size,omitempty"` - Width *int64 `protobuf:"varint,9,opt,name=width,proto3,oneof" json:"width,omitempty"` - Height *int64 `protobuf:"varint,10,opt,name=height,proto3,oneof" json:"height,omitempty"` - Duration *int64 `protobuf:"varint,11,opt,name=duration,proto3,oneof" json:"duration,omitempty"` + state protoimpl.MessageState `protogen:"open.v1"` + ToolName string `protobuf:"bytes,1,opt,name=tool_name,json=toolName,proto3" json:"tool_name,omitempty"` + Type string `protobuf:"bytes,2,opt,name=type,proto3" json:"type,omitempty"` + FileId string `protobuf:"bytes,3,opt,name=file_id,json=fileId,proto3" json:"file_id,omitempty"` + Url string `protobuf:"bytes,4,opt,name=url,proto3" json:"url,omitempty"` + Path string `protobuf:"bytes,5,opt,name=path,proto3" json:"path,omitempty"` + MimeType string `protobuf:"bytes,6,opt,name=mime_type,json=mimeType,proto3" json:"mime_type,omitempty"` + FileName string `protobuf:"bytes,7,opt,name=file_name,json=fileName,proto3" json:"file_name,omitempty"` + FileSize *int64 `protobuf:"varint,8,opt,name=file_size,json=fileSize,proto3,oneof" json:"file_size,omitempty"` + Width *int64 `protobuf:"varint,9,opt,name=width,proto3,oneof" json:"width,omitempty"` + Height *int64 `protobuf:"varint,10,opt,name=height,proto3,oneof" json:"height,omitempty"` + Duration *int64 `protobuf:"varint,11,opt,name=duration,proto3,oneof" json:"duration,omitempty"` + // data carries a sender attachment's bytes on an inbound request. The + // channel frontend downloads the file, but the Gateway process that runs + // the turn never holds the platform credential, so this is the only way + // the model can read a photo or document. It is empty on every other + // direction: stored history and outbound media events carry metadata + // only, and a persisted record strips the bytes. + Data []byte `protobuf:"bytes,12,opt,name=data,proto3" json:"data,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } @@ -478,6 +485,13 @@ func (x *Media) GetDuration() int64 { return 0 } +func (x *Media) GetData() []byte { + if x != nil { + return x.Data + } + return nil +} + type Turn struct { state protoimpl.MessageState `protogen:"open.v1"` TurnId string `protobuf:"bytes,1,opt,name=turn_id,json=turnId,proto3" json:"turn_id,omitempty"` @@ -2890,7 +2904,7 @@ const file_gateway_v1_chat_proto_rawDesc = "" + "parameters\x18\x03 \x01(\tR\n" + "parameters\x12\x16\n" + "\x06output\x18\x04 \x01(\tR\x06output\x12\x14\n" + - "\x05error\x18\x05 \x01(\tR\x05error\"\xdc\x02\n" + + "\x05error\x18\x05 \x01(\tR\x05error\"\xf0\x02\n" + "\x05Media\x12\x1b\n" + "\ttool_name\x18\x01 \x01(\tR\btoolName\x12\x12\n" + "\x04type\x18\x02 \x01(\tR\x04type\x12\x17\n" + @@ -2903,7 +2917,8 @@ const file_gateway_v1_chat_proto_rawDesc = "" + "\x05width\x18\t \x01(\x03H\x01R\x05width\x88\x01\x01\x12\x1b\n" + "\x06height\x18\n" + " \x01(\x03H\x02R\x06height\x88\x01\x01\x12\x1f\n" + - "\bduration\x18\v \x01(\x03H\x03R\bduration\x88\x01\x01B\f\n" + + "\bduration\x18\v \x01(\x03H\x03R\bduration\x88\x01\x01\x12\x12\n" + + "\x04data\x18\f \x01(\fR\x04dataB\f\n" + "\n" + "_file_sizeB\b\n" + "\x06_widthB\t\n" + diff --git a/internal/domain/messaging/inbound.go b/internal/domain/messaging/inbound.go index 7d32b28ba..f40972bcd 100644 --- a/internal/domain/messaging/inbound.go +++ b/internal/domain/messaging/inbound.go @@ -50,10 +50,13 @@ type Inbound struct { // Media carries files the sender attached to this message (photos, // documents, voice, video) with their in-process bytes already // downloaded. Like Page and BudgetKey it is transport-only: it never - // crosses a gRPC or persistence boundary, and the stored Message - // records the attachment as a short textual note in its Text instead, - // because download URLs expire and raw media bytes must not silently - // inflate the transcript store. nil for a text-only message. + // crosses a persistence boundary, and the stored Message records the + // attachment as a short textual note in its Text instead, because + // download URLs expire and raw media bytes must not silently inflate + // the transcript store. It does cross the inbound request to the + // Gateway process that runs the turn -- that process has no platform + // credential, so the bytes have no other way to reach the model. nil + // for a text-only message. Media []MediaAttachment } diff --git a/internal/domain/messaging/media.go b/internal/domain/messaging/media.go index 6c7f370d1..02939e284 100644 --- a/internal/domain/messaging/media.go +++ b/internal/domain/messaging/media.go @@ -1,5 +1,14 @@ package messaging +// MaxInboundAttachmentBytes is the transport ceiling for an attachment a +// channel frontend carries across the inbound wire to the process that runs +// the turn. It is a ceiling, not a policy: a frontend may refuse earlier +// (Telegram's Bot API caps getFile at 20 MB), and anything larger must +// degrade to a notice instead of failing the request that carries it. +// The Gateway's gRPC receive limit is sized from this value, so a maximal +// attachment is accepted rather than rejected as an oversized message. +const MaxInboundAttachmentBytes = 20 << 20 + // MediaAttachment describes a file attached to a message. Platform-agnostic; // platform-specific fields live in Raw. // @@ -53,7 +62,10 @@ type MediaAttachment struct { // Data carries the attachment bytes in-process. An inbound path sets // it after downloading the file; outbound senders never set it and - // read Path or URL instead. It never crosses a wire or persistence - // boundary -- it is a turn-scoped value, not a stored one. + // read Path or URL instead. It crosses the wire in one direction only: + // the inbound request from a channel frontend to the Gateway process + // that runs the turn, because that process never holds the platform + // credential. It is never persisted, and the stored-history and + // outbound-event directions strip it. Data []byte `json:"data,omitempty"` } diff --git a/internal/infrastructure/gatewayrpc/values.go b/internal/infrastructure/gatewayrpc/values.go index 042a65e93..a12af125c 100644 --- a/internal/infrastructure/gatewayrpc/values.go +++ b/internal/infrastructure/gatewayrpc/values.go @@ -64,7 +64,7 @@ func inboundProto(v messaging.Inbound) *pb.Message { m.Page = v.Page m.BudgetKey = v.BudgetKey m.Platform = v.Platform - m.Media = attachmentProtoList(v.Media) + m.Media = inboundAttachmentProtoList(v.Media) return m } @@ -78,7 +78,9 @@ func inboundValue(v *pb.Message) messaging.Inbound { } msg := storedValue(v) msg.Role = messaging.RoleUser - return messaging.Inbound{Message: msg, Page: v.Page, BudgetKey: v.BudgetKey, Platform: v.Platform, Media: attachmentValueList(v.GetMedia())} + // The record keeps the metadata the store persists; the transport media + // carries the bytes the turn model reads, which the record must not hold. + return messaging.Inbound{Message: msg, Page: v.Page, BudgetKey: v.BudgetKey, Platform: v.Platform, Media: inboundAttachmentValueList(v.GetMedia())} } func toolProto(v messaging.ToolCallEvent) *pb.ToolCall { @@ -175,12 +177,12 @@ func intPointer(v *int64) *int { return &n } -// attachmentProtoList renders a message's attachments in wire shape. Data -// is deliberately unmapped: it is a turn-scoped in-process value and must -// never cross the wire, matching the persisted record which strips it too. -// An attachment with no fields beyond Data would produce an empty wire -// message, which is still the honest encoding of "metadata was stripped", -// and never happens for a real attachment. +// attachmentProtoList renders a message's attachments in wire shape for the +// stored-history and outbound-event directions. Data is deliberately +// unmapped: those directions must not carry a turn's bytes, and a persisted +// record strips them too. An attachment with no fields beyond Data would +// produce an empty wire message, which is still the honest encoding of +// "metadata was stripped", and never happens for a real attachment. func attachmentProtoList(media []messaging.MediaAttachment) []*pb.Media { if len(media) == 0 { return nil @@ -195,6 +197,25 @@ func attachmentValueList(list []*pb.Media) []messaging.MediaAttachment { return mapValues(list, attachmentValue) } +// inboundAttachmentProtoList renders a turn's attachments for the inbound +// request. Unlike the stored direction, Data rides along: the channel +// frontend downloads the file, but the Gateway process that runs the turn +// never holds the platform credential, so the bytes have no other way to +// reach the model. +func inboundAttachmentProtoList(media []messaging.MediaAttachment) []*pb.Media { + if len(media) == 0 { + return nil + } + return mapValues(media, inboundAttachmentProto) +} + +func inboundAttachmentValueList(list []*pb.Media) []messaging.MediaAttachment { + if len(list) == 0 { + return nil + } + return mapValues(list, inboundAttachmentValue) +} + func attachmentProto(a messaging.MediaAttachment) *pb.Media { return &pb.Media{Type: a.Type, FileId: a.FileID, Url: a.URL, Path: a.Path, MimeType: a.MIMEType, FileName: a.FileName, FileSize: a.FileSize, Width: int64Pointer(a.Width), Height: int64Pointer(a.Height), Duration: int64Pointer(a.Duration)} } @@ -206,6 +227,18 @@ func attachmentValue(v *pb.Media) messaging.MediaAttachment { return messaging.MediaAttachment{Type: v.Type, FileID: v.FileId, URL: v.Url, Path: v.Path, MIMEType: v.MimeType, FileName: v.FileName, FileSize: v.FileSize, Width: intPointer(v.Width), Height: intPointer(v.Height), Duration: intPointer(v.Duration)} } +func inboundAttachmentProto(a messaging.MediaAttachment) *pb.Media { + pm := attachmentProto(a) + pm.Data = a.Data + return pm +} + +func inboundAttachmentValue(v *pb.Media) messaging.MediaAttachment { + a := attachmentValue(v) + a.Data = v.GetData() + return a +} + func mediaProto(v messaging.MediaEvent) *pb.Media { pm := attachmentProto(v.Attachment) pm.ToolName = v.ToolName diff --git a/internal/infrastructure/gatewayrpc/values_media_test.go b/internal/infrastructure/gatewayrpc/values_media_test.go index b51a10321..905102327 100644 --- a/internal/infrastructure/gatewayrpc/values_media_test.go +++ b/internal/infrastructure/gatewayrpc/values_media_test.go @@ -1,6 +1,7 @@ package gatewayrpc import ( + "bytes" "testing" "github.com/samcharles93/archie-core/internal/domain/messaging" @@ -43,20 +44,24 @@ func TestStoredMediaRoundTrip(t *testing.T) { } // TestInboundMediaRoundTrip mirrors the stored direction for the inbound -// transport context: a frontend that names attachments on Route gets them -// back on the daemon side, minus the bytes which it must carry itself. +// transport context, except that the bytes ride along. The channel frontend +// (archie-messaging) downloads an inbound attachment, but the process that +// runs the turn is archie-gateway/archied, which never holds the Telegram +// token -- so the bytes have to cross this request or the model never sees +// the photo or document it was sent. func TestInboundMediaRoundTrip(t *testing.T) { + raw := []byte("jpeg bytes") in := messaging.Inbound{ Message: messaging.Message{Text: "hi", Sender: "sam"}, Media: []messaging.MediaAttachment{ - {Type: "image", FileID: "f1", MIMEType: "image/jpeg", Data: []byte("jpeg")}, + {Type: "image", FileID: "f1", MIMEType: "image/jpeg", Data: raw}, }, } out := inboundValue(inboundProto(in)) if len(out.Media) != 1 || out.Media[0].FileID != "f1" || out.Media[0].Type != "image" { t.Fatalf("round-tripped inbound media = %#v, want the sender attachment", out.Media) } - if len(out.Media[0].Data) != 0 { - t.Errorf("inbound attachment bytes crossed the wire, want them stripped") + if !bytes.Equal(out.Media[0].Data, raw) { + t.Errorf("inbound attachment bytes = %q, want %q carried to the turn", out.Media[0].Data, raw) } } diff --git a/proto/gateway/v1/chat.proto b/proto/gateway/v1/chat.proto index 2a8889f26..7d5008ff6 100644 --- a/proto/gateway/v1/chat.proto +++ b/proto/gateway/v1/chat.proto @@ -64,9 +64,9 @@ message Message { // constant. Transport-only, never persisted: the session record keeps it. string platform = 10; // media carries attachment metadata for a message that arrived with a - // file. The attachment's bytes never cross this wire: a stored Media - // with tool_name empty is a sender attachment, and the tool_name on - // tool-produced events stays a stream-only field. + // file. The bytes ride only on the inbound request (see Media.data); a + // stored Media with tool_name empty is a sender attachment, and the + // tool_name on tool-produced events stays a stream-only field. repeated Media media = 11; } message ToolCall { @@ -88,6 +88,13 @@ message Media { optional int64 width = 9; optional int64 height = 10; optional int64 duration = 11; + // data carries a sender attachment's bytes on an inbound request. The + // channel frontend downloads the file, but the Gateway process that runs + // the turn never holds the platform credential, so this is the only way + // the model can read a photo or document. It is empty on every other + // direction: stored history and outbound media events carry metadata + // only, and a persisted record strips the bytes. + bytes data = 12; } message Turn { string turn_id = 1;