Merge pull request #561 from samcharles93/worktree-federated-wiggling-milner

feat: video generation via MiniMax, with a channel media-delivery pipeline
This commit is contained in:
sam authored and GitHub committed 2026-08-23 02:54:19 +10:00
commit 6477ceef90
22 files changed
+1842

No files matched your search

+38
View File
@@ -51,6 +51,7 @@ import (
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/tools/minimax"
toolprovider "github.com/samcharles93/archie-core/internal/tools/provider"
builtintoolprovider "github.com/samcharles93/archie-core/internal/tools/provider/builtin"
memorytoolprovider "github.com/samcharles93/archie-core/internal/tools/provider/memory"
@@ -940,6 +941,43 @@ func (b *boot) registerStandaloneTools() {
} else {
log.Info("web fetch disabled")
}
b.registerMinimaxTool(cfg, log)
}
// registerMinimaxTool registers generate_video. Off by default -- see
// MinimaxConfig's doc comment, it spends real API credits per call -- and,
// unlike web_fetch, needs a resolved credential before it can be
// registered at all: a tool advertised with no working key would fail
// every call, the same "don't advertise a broken capability" reasoning as
// disabled-by-config. Split out of registerStandaloneTools to keep that
// function's branching flat rather than nesting this tool's three failure
// modes (resolve error, empty key, registration error) inside it.
func (b *boot) registerMinimaxTool(cfg config.Config, log *slog.Logger) {
if !cfg.Tools.Minimax.IsEnabled() {
log.Info("minimax video generation disabled")
return
}
apiKey, err := cfg.Tools.Minimax.APIKey.Resolve(b.secrets)
if err != nil {
log.Warn("minimax video generation enabled but the API key failed to resolve; tool not registered", "err", err)
return
}
if apiKey == "" {
log.Warn("minimax video generation enabled but no API key is configured; tool not registered")
return
}
entry := minimax.Tool(minimax.Config{Enabled: true, APIKey: apiKey, BaseURL: cfg.Tools.Minimax.BaseURL})
if entry == nil {
return
}
if err := b.toolReg.Register(*entry); err != nil {
log.Warn("generate_video registration failed", "err", err)
return
}
log.Info("minimax video generation enabled")
}
// buildDaemon constructs the daemon and hands the dashboard the handles
+38
View File
@@ -22,6 +22,10 @@ func (s *recordingStream) ToolCall(event gateway.ToolCallEvent) {
s.events = append(s.events, "tool:"+event.Name+":"+event.Parameters+":"+event.Summary())
}
func (s *recordingStream) Media(event gateway.MediaEvent) {
s.events = append(s.events, "media:"+event.ToolName+":"+event.Attachment.Type)
}
func streamOf(parts ...core.StreamPart) <-chan core.StreamPart {
ch := make(chan core.StreamPart, len(parts))
for _, part := range parts {
@@ -86,6 +90,40 @@ func TestDrainChatStream(t *testing.T) {
},
wantEvents: nil,
},
{
// A tool's output carrying a tools.MultimodalResult envelope
// must report both the ordinary tool-call event (so the turn
// narrates what ran) and a Media event per URL, so the
// channel has something to actually deliver.
name: "a tool result carrying MultimodalResult URLs reports Media",
parts: []core.StreamPart{
{Type: core.StreamPartToolCall, ToolCall: &core.ToolCall{ToolCallID: "1", ToolName: "generate_video"}},
{Type: core.StreamPartToolResult, ToolResult: &core.ToolResult{
ToolCallID: "1",
ToolName: "generate_video",
Output: `{"is_multimodal":true,"urls":[{"type":"video","url":"https://x/v"}]}`,
}},
},
wantEvents: []string{
`tool:generate_video::{"is_multimodal":true,"urls":[{"type":"video","url":"https://x/v"}]}`,
"media:generate_video:video",
},
},
{
// An ordinary JSON tool result that happens to be a JSON
// object but isn't a MultimodalResult (no is_multimodal, or
// false) must not be misread as carrying media.
name: "a plain JSON tool result reports no Media event",
parts: []core.StreamPart{
{Type: core.StreamPartToolCall, ToolCall: &core.ToolCall{ToolCallID: "1", ToolName: "read_file"}},
{Type: core.StreamPartToolResult, ToolResult: &core.ToolResult{
ToolCallID: "1",
ToolName: "read_file",
Output: `{"path":"a.txt","content":"hello"}`,
}},
},
wantEvents: []string{`tool:read_file::{"path":"a.txt","content":"hello"}`},
},
}
for _, tc := range tests {
+27
View File
@@ -2,6 +2,7 @@ package main
import (
"context"
"encoding/json"
"fmt"
"log/slog"
"os"
@@ -330,11 +331,37 @@ func drainChatStream(parts <-chan core.StreamPart, turn gateway.TurnStream) stri
Output: part.ToolResult.Output,
Err: part.ToolResult.Error,
})
for _, ref := range multimodalMediaRefs(part.ToolResult.Output) {
turn.Media(gateway.MediaEvent{
ToolName: name,
Attachment: gateway.MediaAttachment{Type: ref.Type, URL: ref.URL},
})
}
}
}
return sb.String()
}
// multimodalMediaRefs extracts the URLs a tool result carries when its
// output is a tools.MultimodalResult, so drainChatStream can report each as
// a gateway.MediaEvent alongside the ordinary ToolCall event.
//
// output is decoded with json.Unmarshal directly rather than checked
// against a schema first: most tool output is plain text or unrelated
// JSON, and unmarshalling into MultimodalResult simply leaves IsMultimodal
// false for anything that doesn't match, which is exactly "not multimodal"
// -- no separate detection step earns its keep here.
func multimodalMediaRefs(output string) []tools.MediaRef {
if output == "" {
return nil
}
var result tools.MultimodalResult
if err := json.Unmarshal([]byte(output), &result); err != nil || !result.IsMultimodal {
return nil
}
return result.URLs
}
// chatTitleGenerator proposes session titles through the chat model. It
// is a pure proposal: it persists nothing, so a failed or slow title
// call can never corrupt conversation history or fail the turn. The
+13
View File
@@ -279,3 +279,16 @@ gate_max_failures = 5
# # dial time rather than on the URL string, so a public name that resolves to
# # a private address is refused too. Turn this on only for a homelab endpoint
# # you intend Archie to reach.
# The generate_video tool: text-to-video via MiniMax's API. Off by default,
# unlike web_fetch -- this spends real API credits per call, so it needs an
# explicit opt-in and a working key before it is registered at all.
# [tools.minimax]
# enabled = true
# api_key = { engine = "env", key = "MINIMAX_API_KEY" }
# base_url = "" # override the API host; leave unset in normal operation
# # Generation is synchronous from the model's point of view: the tool call
# # blocks until MiniMax reports the video ready or failed, which can take
# # several minutes. The result is a hosted URL delivered through whatever
# # channel supports gateway.MediaSender (Telegram today); channels without
# # that support get the URL as a plain link in the reply text instead.
+88
View File
@@ -30,6 +30,10 @@ const (
// toolCallPrefix opens an inline tool-activity line.
toolCallPrefix = "🔧 "
// fallbackMediaLinePrefix opens the line Media appends when it could
// not deliver an attachment inline, so the user still gets the asset.
fallbackMediaLinePrefix = "📎 "
// liveBodyMaxRunes bounds one mid-turn frame. Telegram rejects a
// message over its character limit outright, so an unbounded frame
// means every edit past that point fails and the live message freezes
@@ -77,6 +81,19 @@ type liveReply struct {
// interval throttles updates; zero renders every change.
interval time.Duration
// mediaWg lets tests (and a future bounded drain, mirroring
// abandonAllLive) wait for in-flight Media deliveries. Callers other
// than tests must not block on it: Media is fire-and-forget by
// contract, same as Delta and ToolCall.
mediaWg sync.WaitGroup
// newMediaSender builds the MediaSender Media delivers through.
// Defaults to g.NewMediaSender; tests override it to inject a sender
// with fixed Capabilities(), which the real Telegram one can't
// express (it always reports Media: true) but a future channel or a
// capability-limited deployment might.
newMediaSender func(b *bot.Bot, chatID int64, threadID int) gateway.MediaSender
cancelRender context.CancelFunc
renderRequests chan chan struct{}
renderDone chan struct{}
@@ -124,6 +141,7 @@ func (g *Gateway) newLiveReply(ctx context.Context, b *bot.Bot, chatID int64, me
messageThreadID: messageThreadID,
showToolCalls: showToolCalls,
interval: liveInterval,
newMediaSender: g.NewMediaSender,
cancelRender: cancelRender,
renderRequests: make(chan chan struct{}, 1),
renderDone: make(chan struct{}),
@@ -318,6 +336,76 @@ func (l *liveReply) ToolCall(event gateway.ToolCallEvent) {
l.requestRender()
}
// mediaSendTimeout bounds one Media delivery. It is independent of the
// render loop's own lifecycle (unlike answerBuf/toolLines, which a
// /restart abandons via abandonAllLive): an upload in flight when the live
// reply finalizes should still be allowed to land, since the asset is worth
// delivering on its own even after the surrounding turn is done narrating.
const mediaSendTimeout = 30 * time.Second
// Media delivers the attachment through the media-specific Bot API, off the
// generating goroutine: unlike Delta/ToolCall, this is a real network
// upload, and TurnStream implementations must not block generation on one.
// It satisfies gateway.TurnStream.
//
// A missing URL is silently skipped rather than surfaced: an attachment
// telegramMediaSender.SendMedia would reject as invalid_message has nothing
// worth falling back to either, and Media has no error return to report it
// through.
func (l *liveReply) Media(event gateway.MediaEvent) {
if event.Attachment.URL == "" {
return
}
l.mediaWg.Go(func() {
sender := l.newMediaSender(l.b, l.chatID, l.messageThreadID)
// Checked before attempting delivery, not just on failure: that is
// the entire point of CapabilityReporter over attempt-then-catch
// -- a sender that already knows it cannot deliver a given media
// kind should never cost a doomed network round trip to find out.
if !gateway.CapabilitiesOf(sender).Media {
l.g.log.Debug("channel cannot deliver media inline, falling back to a link",
"tool", event.ToolName, "type", event.Attachment.Type)
l.appendFallbackLine(event.Attachment)
return
}
ctx, cancel := context.WithTimeout(context.Background(), mediaSendTimeout)
defer cancel()
_, err := sender.SendMedia(ctx, gateway.MessageEvent{
Media: []gateway.MediaAttachment{event.Attachment},
})
if err == nil {
return
}
l.g.log.Warn("media delivery failed, falling back to a link",
"tool", event.ToolName, "type", event.Attachment.Type, "error", err)
l.appendFallbackLine(event.Attachment)
})
}
// appendFallbackLine renders att as a visible link in the reply, for a
// MediaEvent that could not be (or was not attempted to be) delivered
// inline.
func (l *liveReply) appendFallbackLine(att gateway.MediaAttachment) {
line := fallbackMediaLinePrefix + bot.EscapeMarkdown(att.Type) + ": " + att.URL
l.mu.Lock()
l.toolLines = append(l.toolLines, line)
l.mu.Unlock()
l.requestRender()
}
// waitMedia blocks until every Media delivery started so far has finished.
// Tests only: production callers never wait on Media's fire-and-forget
// goroutines.
func (l *liveReply) waitMedia() {
l.mediaWg.Wait()
}
// render writes the current buffer, cursor and all, to the live message.
func (l *liveReply) render(ctx context.Context) {
l.mu.Lock()
+119
View File
@@ -940,3 +940,122 @@ func TestGatewayRegisterLiveAfterStopAbandonsImmediately(t *testing.T) {
t.Fatal("a liveReply registered after stop was never abandoned")
}
}
// Media must actually deliver the attachment through the Bot API's
// media-specific endpoint, not just buffer it like Delta/ToolCall --
// there is no later render pass that turns a MediaEvent into anything.
func TestLiveReplyMediaDeliversTheAttachment(t *testing.T) {
live, calls := newTestLiveReply(t, false)
live.Media(gateway.MediaEvent{
ToolName: "video_gen",
Attachment: gateway.MediaAttachment{Type: "video", URL: "https://example.com/v.mp4"},
})
live.waitMedia()
if len(*calls) != 1 {
t.Fatalf("api calls = %d, want 1", len(*calls))
}
if (*calls)[0].method != "sendVideo" {
t.Fatalf("called %q, want sendVideo", (*calls)[0].method)
}
}
// An event with no URL has nothing to deliver and nothing to fall back to,
// so it must not reach the API at all.
func TestLiveReplyMediaWithNoURLIsANoop(t *testing.T) {
live, calls := newTestLiveReply(t, false)
live.Media(gateway.MediaEvent{ToolName: "video_gen", Attachment: gateway.MediaAttachment{Type: "video"}})
live.waitMedia()
if len(*calls) != 0 {
t.Fatalf("api calls = %d, want 0", len(*calls))
}
}
// When delivery fails, the user must still get the URL as a link rather
// than silence: a generated video that can't be uploaded is still a result
// worth handing back.
func TestLiveReplyMediaFallsBackToALinkOnFailure(t *testing.T) {
failing := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"ok":false,"error_code":400,"description":"boom"}`))
}))
t.Cleanup(failing.Close)
b, err := bot.New("1:test", bot.WithServerURL(failing.URL), bot.WithSkipGetMe())
if err != nil {
t.Fatalf("new test bot: %v", err)
}
g := New("1:test", "", "", []int64{42}, slog.New(slog.DiscardHandler))
live := g.newLiveReply(context.Background(), b, 7, 0, false)
t.Cleanup(live.stopRendering)
live.interval = 0
live.Media(gateway.MediaEvent{
ToolName: "video_gen",
Attachment: gateway.MediaAttachment{Type: "video", URL: "https://example.com/v.mp4"},
})
live.waitMedia()
live.mu.Lock()
lines := strings.Join(live.toolLines, "\n")
live.mu.Unlock()
if !strings.Contains(lines, "https://example.com/v.mp4") {
t.Fatalf("fallback lines = %q, want it to contain the asset URL", lines)
}
}
// capabilityLimitedSender reports Media: false regardless of what it is
// asked to send, so tests can prove Media actually consults
// gateway.CapabilitiesOf before attempting delivery, rather than always
// attempting and only ever falling back on a network failure.
type capabilityLimitedSender struct {
sendCalled bool
}
func (s *capabilityLimitedSender) SendMedia(context.Context, gateway.MessageEvent) (gateway.SendResult, error) {
s.sendCalled = true
return gateway.SendResult{Success: true}, nil
}
func (s *capabilityLimitedSender) Capabilities() gateway.AdapterCapabilities {
return gateway.AdapterCapabilities{Media: false}
}
var (
_ gateway.MediaSender = (*capabilityLimitedSender)(nil)
_ gateway.CapabilityReporter = (*capabilityLimitedSender)(nil)
)
// When the bound sender reports it cannot deliver media at all, Media must
// go straight to the text-link fallback without attempting SendMedia --
// checking capability first is the whole point of CapabilityReporter over
// attempt-then-catch, so a call site that ignores it makes the mechanism
// dead weight.
func TestLiveReplyMediaSkipsDeliveryWhenCapabilityReportsUnsupported(t *testing.T) {
live, calls := newTestLiveReply(t, false)
sender := &capabilityLimitedSender{}
live.newMediaSender = func(*bot.Bot, int64, int) gateway.MediaSender { return sender }
live.Media(gateway.MediaEvent{
ToolName: "video_gen",
Attachment: gateway.MediaAttachment{Type: "video", URL: "https://example.com/v.mp4"},
})
live.waitMedia()
if sender.sendCalled {
t.Error("SendMedia was called despite Capabilities().Media == false")
}
if len(*calls) != 0 {
t.Errorf("api calls = %d, want 0 (capability check should short-circuit before any request)", len(*calls))
}
live.mu.Lock()
lines := strings.Join(live.toolLines, "\n")
live.mu.Unlock()
if !strings.Contains(lines, "https://example.com/v.mp4") {
t.Fatalf("fallback lines = %q, want it to contain the asset URL", lines)
}
}
+168
View File
@@ -0,0 +1,168 @@
package telegram
import (
"context"
"errors"
"fmt"
"github.com/go-telegram/bot"
"github.com/go-telegram/bot/models"
"github.com/samcharles93/archie-core/internal/gateway"
)
// telegramMediaSender delivers a MessageEvent's attachment through the
// media-specific Bot API methods (sendVideo, sendPhoto, ...) rather than
// sendMessage, which cannot carry a file at all.
//
// It captures the *bot.Bot at construction rather than reading the
// Gateway's shared field, matching telegramApprover: a sender belongs to
// the launch that built it, so a /restart abandons in-flight sends with
// the outgoing bot instance instead of silently redirecting them through
// the new one. That is the same lifetime rule the per-launch turns
// registry documents.
//
// Delivery is URL-only. A MediaAttachment.FileID identifies a file on the
// platform it was uploaded from and is meaningless as an outbound handle
// here, so only URL is accepted; uploading local bytes is a separate
// concern from routing a generated asset to a chat.
type telegramMediaSender struct {
bot *bot.Bot
chatID int64
threadID int
}
var (
_ gateway.MediaSender = (*telegramMediaSender)(nil)
_ gateway.CapabilityReporter = (*telegramMediaSender)(nil)
)
// NewMediaSender returns a MediaSender bound to one chat and to the bot
// instance of the launch that created it. Construct it per launch, from
// the same b that handled the update, never from a stored field.
func (g *Gateway) NewMediaSender(b *bot.Bot, chatID int64, threadID int) gateway.MediaSender {
return &telegramMediaSender{bot: b, chatID: chatID, threadID: threadID}
}
// Capabilities reports Media support. Telegram implements every media
// kind MediaAttachment can describe, so this is unconditionally true.
func (s *telegramMediaSender) Capabilities() gateway.AdapterCapabilities {
return gateway.AdapterCapabilities{Media: true}
}
// errNoMedia and errNoURL are the two ways an event can be undeliverable
// before any request is made.
var (
errNoMedia = errors.New("message event carries no media attachment")
errNoURL = errors.New("media attachment has no URL")
)
// SendMedia delivers the event's first attachment, captioned with the
// event text. Only the first is sent: a caption belongs to one file, and
// batching several into a media group is a distinct API with its own
// caption semantics.
func (s *telegramMediaSender) SendMedia(ctx context.Context, event gateway.MessageEvent) (gateway.SendResult, error) {
if len(event.Media) == 0 {
return invalidMedia(errNoMedia)
}
att := event.Media[0]
if att.URL == "" {
return invalidMedia(fmt.Errorf("%w (type %q)", errNoURL, att.Type))
}
msg, err := s.dispatch(ctx, att, event.Text)
if err != nil {
if errors.Is(err, errUnsupportedMediaType) {
return invalidMedia(err)
}
res := classifySendError(err)
res.Error = fmt.Errorf("send %s: %w", att.Type, err)
return res, res.Error
}
id := ""
if msg != nil {
id = fmt.Sprintf("%d", msg.ID)
}
return gateway.SendResult{Success: true, MessageID: id}, nil
}
var errUnsupportedMediaType = errors.New("unsupported media type")
// dispatch routes an attachment to the Bot API method for its kind. The
// media type, not the MessageEvent type, decides: the event type describes
// the message while the attachment describes the file, and Telegram
// rejects a video sent through sendPhoto.
func (s *telegramMediaSender) dispatch(ctx context.Context, att gateway.MediaAttachment, caption string) (*models.Message, error) {
file := &models.InputFileString{Data: att.URL}
switch att.Type {
case "video":
p := &bot.SendVideoParams{ChatID: s.chatID, Video: file, Caption: caption}
p.MessageThreadID = s.threadID
if att.Width != nil {
p.Width = *att.Width
}
if att.Height != nil {
p.Height = *att.Height
}
if att.Duration != nil {
p.Duration = *att.Duration
}
return s.bot.SendVideo(ctx, p)
case "image":
p := &bot.SendPhotoParams{ChatID: s.chatID, Photo: file, Caption: caption}
p.MessageThreadID = s.threadID
return s.bot.SendPhoto(ctx, p)
case "audio":
p := &bot.SendAudioParams{ChatID: s.chatID, Audio: file, Caption: caption}
p.MessageThreadID = s.threadID
if att.Duration != nil {
p.Duration = *att.Duration
}
return s.bot.SendAudio(ctx, p)
case "document":
p := &bot.SendDocumentParams{ChatID: s.chatID, Document: file, Caption: caption}
p.MessageThreadID = s.threadID
return s.bot.SendDocument(ctx, p)
default:
return nil, fmt.Errorf("%w %q", errUnsupportedMediaType, att.Type)
}
}
// invalidMedia reports a failure that was detected before any request was
// made. Never retryable: resending an event that carries nothing, or names
// a type Telegram has no method for, fails identically every time.
func invalidMedia(err error) (gateway.SendResult, error) {
return gateway.SendResult{
Success: false,
Retryable: false,
Error: err,
ErrorCode: "invalid_message",
}, err
}
// classifySendError maps a Bot API failure onto SendResult's error
// vocabulary so a caller can decide on retry without inspecting
// Telegram-specific errors.
//
// The library reports API failures as sentinel errors (bot.ErrorBadRequest
// and friends), not as typed values, so these are errors.Is checks. A
// failure matching no sentinel is a transport error or a 5xx, both of
// which may yet succeed -- hence retryable, rather than defaulting to
// permanent and silently dropping a deliverable asset.
func classifySendError(err error) gateway.SendResult {
res := gateway.SendResult{Success: false, Error: err}
switch {
case bot.IsTooManyRequestsError(err) || errors.Is(err, bot.ErrorTooManyRequests):
res.Retryable, res.ErrorCode = true, "rate_limited"
case errors.Is(err, bot.ErrorUnauthorized), errors.Is(err, bot.ErrorForbidden):
res.Retryable, res.ErrorCode = false, "auth"
case errors.Is(err, bot.ErrorBadRequest), errors.Is(err, bot.ErrorNotFound):
res.Retryable, res.ErrorCode = false, "invalid_message"
default:
res.Retryable, res.ErrorCode = true, "network"
}
return res
}
+263
View File
@@ -0,0 +1,263 @@
package telegram
import (
"context"
"log/slog"
"maps"
"net/http"
"net/http/httptest"
"strings"
"sync"
"testing"
"github.com/go-telegram/bot"
"github.com/samcharles93/archie-core/internal/gateway"
)
// mediaAPI stands in for the Bot API, recording which sendX method was
// called and the form values it received.
type mediaAPI struct {
mu sync.Mutex
method string
form map[string]string
body string
}
func newMediaAPI() (*mediaAPI, *httptest.Server) {
api := &mediaAPI{form: map[string]string{}, body: `{"ok":true,"result":{"message_id":77}}`}
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
api.mu.Lock()
parts := strings.Split(strings.Trim(r.URL.Path, "/"), "/")
api.method = parts[len(parts)-1]
if err := r.ParseMultipartForm(1 << 20); err == nil {
for k, v := range r.Form {
if len(v) > 0 {
api.form[k] = v[0]
}
}
}
body := api.body
api.mu.Unlock()
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(body))
}))
return api, srv
}
func (m *mediaAPI) called() (string, map[string]string) {
m.mu.Lock()
defer m.mu.Unlock()
form := make(map[string]string, len(m.form))
maps.Copy(form, m.form)
return m.method, form
}
func newTestMediaSender(t *testing.T, serverURL string, chatID int64, threadID int) gateway.MediaSender {
t.Helper()
b, err := bot.New("1:test", bot.WithServerURL(serverURL), bot.WithSkipGetMe())
if err != nil {
t.Fatalf("new test bot: %v", err)
}
g := New("1:test", "", "", []int64{42}, slog.New(slog.DiscardHandler))
return g.NewMediaSender(b, chatID, threadID)
}
// Each media kind must reach its own Bot API method -- a video sent via
// sendPhoto is rejected by Telegram, and a document fallback would silently
// downgrade playback.
func TestSendMedia_RoutesByMediaType(t *testing.T) {
tests := []struct {
name string
mediaType string
msgType gateway.MessageType
wantMethod string
wantField string
}{
{"video", "video", gateway.MsgVideo, "sendVideo", "video"},
{"image", "image", gateway.MsgImage, "sendPhoto", "photo"},
{"audio", "audio", gateway.MsgAudio, "sendAudio", "audio"},
{"document", "document", gateway.MsgDocument, "sendDocument", "document"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
api, srv := newMediaAPI()
defer srv.Close()
sender := newTestMediaSender(t, srv.URL, 555, 0)
res, err := sender.SendMedia(context.Background(), gateway.MessageEvent{
Type: tt.msgType,
Text: "a caption",
Media: []gateway.MediaAttachment{{
Type: tt.mediaType,
URL: "https://example.com/asset",
}},
})
if err != nil {
t.Fatalf("SendMedia: %v", err)
}
if !res.Success {
t.Fatalf("expected success, got %+v", res)
}
method, form := api.called()
if method != tt.wantMethod {
t.Errorf("called %q, want %q", method, tt.wantMethod)
}
if form[tt.wantField] != "https://example.com/asset" {
t.Errorf("field %q = %q, want the asset URL", tt.wantField, form[tt.wantField])
}
if form["caption"] != "a caption" {
t.Errorf("caption = %q, want %q", form["caption"], "a caption")
}
if form["chat_id"] != "555" {
t.Errorf("chat_id = %q, want the bound chat", form["chat_id"])
}
})
}
}
// The sender is bound to a chat at construction, matching telegramApprover.
// A thread ID must survive to the API or replies land outside the topic.
func TestSendMedia_UsesBoundThread(t *testing.T) {
api, srv := newMediaAPI()
defer srv.Close()
sender := newTestMediaSender(t, srv.URL, 555, 99)
if _, err := sender.SendMedia(context.Background(), gateway.MessageEvent{
Type: gateway.MsgVideo,
Media: []gateway.MediaAttachment{{Type: "video", URL: "https://example.com/v.mp4"}},
}); err != nil {
t.Fatalf("SendMedia: %v", err)
}
_, form := api.called()
if form["message_thread_id"] != "99" {
t.Errorf("message_thread_id = %q, want 99", form["message_thread_id"])
}
}
// An event with no attachment must not reach the API at all: Telegram
// rejects an empty media field, and reporting success would leave the
// caller believing a video was delivered.
func TestSendMedia_NoAttachmentIsAnError(t *testing.T) {
api, srv := newMediaAPI()
defer srv.Close()
sender := newTestMediaSender(t, srv.URL, 555, 0)
res, err := sender.SendMedia(context.Background(), gateway.MessageEvent{Type: gateway.MsgVideo})
if err == nil {
t.Fatal("expected an error for an event carrying no media")
}
if res.Success {
t.Error("expected Success=false")
}
if res.Retryable {
t.Error("a missing attachment is not retryable")
}
if res.ErrorCode != "invalid_message" {
t.Errorf("ErrorCode = %q, want invalid_message", res.ErrorCode)
}
if method, _ := api.called(); method != "" {
t.Errorf("called the API (%q) despite having nothing to send", method)
}
}
// An attachment with no URL cannot be sent: this sender is URL-only, and
// a FileID belongs to the platform it was uploaded from.
func TestSendMedia_MissingURLIsAnError(t *testing.T) {
_, srv := newMediaAPI()
defer srv.Close()
sender := newTestMediaSender(t, srv.URL, 555, 0)
res, err := sender.SendMedia(context.Background(), gateway.MessageEvent{
Type: gateway.MsgVideo,
Media: []gateway.MediaAttachment{{Type: "video"}},
})
if err == nil {
t.Fatal("expected an error for an attachment with no URL")
}
if res.ErrorCode != "invalid_message" {
t.Errorf("ErrorCode = %q, want invalid_message", res.ErrorCode)
}
}
// An unroutable media type must be reported, not guessed at.
func TestSendMedia_UnknownTypeIsAnError(t *testing.T) {
_, srv := newMediaAPI()
defer srv.Close()
sender := newTestMediaSender(t, srv.URL, 555, 0)
res, err := sender.SendMedia(context.Background(), gateway.MessageEvent{
Type: gateway.MsgVideo,
Media: []gateway.MediaAttachment{{Type: "hologram", URL: "https://example.com/h"}},
})
if err == nil {
t.Fatal("expected an error for an unsupported media type")
}
if res.ErrorCode != "invalid_message" {
t.Errorf("ErrorCode = %q, want invalid_message", res.ErrorCode)
}
}
// Telegram failures must be classified so callers can decide on retry,
// rather than every failure looking alike.
//
// The bot library branches on the JSON \`error_code\` field of the API
// response, not the HTTP status, so each stub has to carry the matching
// integer.
func TestSendMedia_ClassifiesAPIFailures(t *testing.T) {
tests := []struct {
name string
body string
wantCode string
wantRetryable bool
}{
{"rate limited", `{"ok":false,"error_code":429,"description":"Too Many Requests","parameters":{"retry_after":1}}`, "rate_limited", true},
{"auth", `{"ok":false,"error_code":401,"description":"Unauthorized"}`, "auth", false},
{"bad request", `{"ok":false,"error_code":400,"description":"wrong file identifier"}`, "invalid_message", false},
{"server error", `{"ok":false,"error_code":500,"description":"boom"}`, "network", true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
api, srv := newMediaAPI()
defer srv.Close()
api.mu.Lock()
api.body = tt.body
api.mu.Unlock()
sender := newTestMediaSender(t, srv.URL, 555, 0)
res, err := sender.SendMedia(context.Background(), gateway.MessageEvent{
Type: gateway.MsgVideo,
Media: []gateway.MediaAttachment{{Type: "video", URL: "https://example.com/v.mp4"}},
})
if err == nil {
t.Fatal("expected an error")
}
if res.Success {
t.Error("expected Success=false")
}
if res.ErrorCode != tt.wantCode {
t.Errorf("ErrorCode = %q, want %q", res.ErrorCode, tt.wantCode)
}
if res.Retryable != tt.wantRetryable {
t.Errorf("Retryable = %v, want %v", res.Retryable, tt.wantRetryable)
}
})
}
}
// The capability must be reported, so a caller can check support without
// attempting a doomed send.
func TestMediaSender_ReportsMediaCapability(t *testing.T) {
_, srv := newMediaAPI()
defer srv.Close()
sender := newTestMediaSender(t, srv.URL, 555, 0)
if caps := gateway.CapabilitiesOf(sender); !caps.Media {
t.Error("telegram media sender does not report the Media capability")
}
}
+23
View File
@@ -349,11 +349,34 @@ type WebFetchConfig struct {
// absent setting as enabled.
func (c WebFetchConfig) IsEnabled() bool { return c.Enabled == nil || *c.Enabled }
// MinimaxConfig controls the generate_video tool
// (internal/tools/minimax). Unlike WebFetchConfig, absent is disabled, not
// enabled: web_fetch needs no credential and is safe as a silent default,
// while this tool spends real API credits per call, so it stays off until
// an operator explicitly turns it on and supplies a key.
type MinimaxConfig struct {
// Enabled advertises the tool. Defaults to false (see the type doc).
Enabled bool `toml:"enabled" yaml:"enabled" json:"enabled"`
// APIKey authenticates against the MiniMax API.
APIKey secret.SecretRef `toml:"api_key" yaml:"api_key" json:"-"`
// BaseURL overrides the API host. Empty uses the client's built-in
// default. Exists for a proxy or a self-hosted-compatible endpoint,
// not expected to be set in normal operation.
BaseURL string `toml:"base_url" yaml:"base_url" json:"base_url,omitempty"`
}
// IsEnabled reports whether the video-generation tool should be
// registered.
func (c MinimaxConfig) IsEnabled() bool { return c.Enabled }
// ToolsConfig holds MCP server and tool policy configuration.
type ToolsConfig struct {
MCPServers []MCPServer `toml:"mcp_servers" yaml:"mcp_servers" json:"mcp_servers"`
Policy ToolPolicy `toml:"tool_policy" yaml:"tool_policy" json:"tool_policy"`
WebFetch WebFetchConfig `toml:"web_fetch" yaml:"web_fetch" json:"web_fetch"`
Minimax MinimaxConfig `toml:"minimax" yaml:"minimax" json:"minimax"`
}
// Config is the daemon configuration.
+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()
+299
View File
@@ -0,0 +1,299 @@
// Package minimax generates video through MiniMax's video-generation API:
// https://platform.minimax.io/docs/api-reference/video-generation-v2-create
//
// Generation is asynchronous on MiniMax's side (submit a job, poll for a
// result), but archied's tool subsystem has no async-tool flow control (see
// tools.ToolEntry.IsAsync's doc comment), so GenerateAndWait blocks the
// calling goroutine -- a tool call, not the model's own generating
// goroutine -- submitting and polling until the job reaches a terminal
// status or MaxWait elapses.
package minimax
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"strings"
"time"
)
const (
// defaultBaseURL is MiniMax's production API host. Overridable for
// tests and for an operator pointed at a proxy.
defaultBaseURL = "https://api.minimax.io"
// defaultModel is the only model documented for this endpoint.
defaultModel = "MiniMax-H3"
// defaultResolution and defaultDuration match the middle of MiniMax's
// documented ranges (768P/2K; 4-15s) rather than the extremes, so an
// unconfigured request is neither the cheapest-lowest-quality nor the
// most expensive option by default.
defaultResolution = "768P"
defaultDuration = 6
// defaultPollInterval and defaultMaxWait bound one generation. MiniMax
// documents no expected completion time, so these are a starting
// guess: frequent enough to feel responsive, bounded low enough that
// a stuck job fails a chat turn in minutes rather than hanging it.
defaultPollInterval = 5 * time.Second
defaultMaxWait = 5 * time.Minute
// defaultTimeout bounds one HTTP call (create or a single query), not
// the whole generate-and-wait loop -- that is MaxWait.
defaultTimeout = 30 * time.Second
)
// Config controls the client. The zero value is disabled.
type Config struct {
// Enabled advertises the tool. When false, Tool returns nil.
Enabled bool
// APIKey authenticates every request as a Bearer token.
APIKey string
// BaseURL overrides the API host. Empty uses defaultBaseURL.
BaseURL string
// Timeout bounds one HTTP call. Zero uses defaultTimeout.
Timeout time.Duration
// PollInterval is the delay between status queries. Zero uses
// defaultPollInterval.
PollInterval time.Duration
// MaxWait bounds the whole submit-and-poll loop. Zero uses
// defaultMaxWait.
MaxWait time.Duration
// Sleep delays between polls. Nil uses time.Sleep. Tests inject a
// no-op or counting stand-in so a poll loop that spans MaxWait does
// not actually take that long to run.
Sleep func(time.Duration)
}
// Client generates video through the MiniMax API.
type Client struct {
cfg Config
http *http.Client
}
// New builds a Client, filling unset Config fields with their defaults.
func New(cfg Config) *Client {
if cfg.BaseURL == "" {
cfg.BaseURL = defaultBaseURL
}
if cfg.Timeout <= 0 {
cfg.Timeout = defaultTimeout
}
if cfg.PollInterval <= 0 {
cfg.PollInterval = defaultPollInterval
}
if cfg.MaxWait <= 0 {
cfg.MaxWait = defaultMaxWait
}
if cfg.Sleep == nil {
cfg.Sleep = time.Sleep
}
return &Client{cfg: cfg, http: &http.Client{Timeout: cfg.Timeout}}
}
// GenerateRequest is one text-to-video job. Image-to-video (image_url
// content items) is not implemented: the first consumer is text-only
// generation, and adding image references is a schema-and-routing change
// this can grow into rather than needing up front.
type GenerateRequest struct {
// Prompt is the required text description (MiniMax caps this at 7000
// characters; that is not separately enforced here, the API rejects
// an oversized prompt with a 400 the caller sees).
Prompt string
// Resolution is "768P" or "2K". Empty uses defaultResolution.
Resolution string
// Duration is the clip length in seconds, 4-15. Zero uses
// defaultDuration.
Duration int
// Ratio is the aspect ratio (see the package doc's API reference for
// the allowed set). Empty uses "adaptive", MiniMax's own default.
Ratio string
}
// GenerateAndWait submits req and blocks until MiniMax reports a terminal
// status, returning the hosted video URL on success.
func (c *Client) GenerateAndWait(ctx context.Context, req GenerateRequest) (string, error) {
taskID, err := c.create(ctx, req)
if err != nil {
return "", err
}
// elapsed is tracked from the injected Sleep calls rather than a real
// time.Now() deadline, so a test that fakes Sleep as an instant
// counter also makes this loop terminate instantly instead of
// spinning in real wall-clock time until an unfaked clock catches up.
var elapsed time.Duration
for {
if err := ctx.Err(); err != nil {
return "", fmt.Errorf("minimax: task %s: %w", taskID, err)
}
task, err := c.query(ctx, taskID)
if err != nil {
return "", err
}
switch task.Status {
case "succeeded":
if task.Content.URL == "" {
return "", fmt.Errorf("minimax: task %s succeeded but reported no video url", taskID)
}
return task.Content.URL, nil
case "failed", "cancelled":
return "", fmt.Errorf("minimax: task %s %s: %s", taskID, task.Status, task.errorMessage())
}
if elapsed >= c.cfg.MaxWait {
return "", fmt.Errorf("minimax: task %s timed out after %v waiting for completion (last status %q)",
taskID, c.cfg.MaxWait, task.Status)
}
c.cfg.Sleep(c.cfg.PollInterval)
elapsed += c.cfg.PollInterval
}
}
type createResponse struct {
TaskID string `json:"task_id"`
}
// create submits req and returns the task ID MiniMax assigned.
func (c *Client) create(ctx context.Context, req GenerateRequest) (string, error) {
resolution := req.Resolution
if resolution == "" {
resolution = defaultResolution
}
duration := req.Duration
if duration == 0 {
duration = defaultDuration
}
ratio := req.Ratio
if ratio == "" {
ratio = "adaptive"
}
body := map[string]any{
"model": defaultModel,
"resolution": resolution,
"duration": duration,
"ratio": ratio,
"content": []map[string]string{
{"type": "text", "text": req.Prompt},
},
}
var out createResponse
if err := c.doJSON(ctx, http.MethodPost, "/v2/video_generation", body, &out); err != nil {
return "", err
}
if out.TaskID == "" {
return "", errors.New("minimax: create response carried no task_id")
}
return out.TaskID, nil
}
// taskStatus is the polled state of one generation job.
type taskStatus struct {
Status string `json:"status"`
Error *struct {
Code string `json:"code"`
Message string `json:"message"`
} `json:"error,omitempty"`
Content struct {
URL string `json:"url"`
} `json:"content"`
}
// errorMessage reports the platform's own failure detail, falling back to
// a placeholder when MiniMax reported a terminal failure with no error
// object -- which the docs don't rule out.
func (t taskStatus) errorMessage() string {
if t.Error == nil || t.Error.Message == "" {
return "no error detail reported"
}
return t.Error.Message
}
type queryResponse struct {
Task taskStatus `json:"task"`
}
// query fetches the current status of taskID.
func (c *Client) query(ctx context.Context, taskID string) (taskStatus, error) {
var out queryResponse
path := "/v2/query/video_generation/" + taskID
if err := c.doJSON(ctx, http.MethodGet, path, nil, &out); err != nil {
return taskStatus{}, err
}
return out.Task, nil
}
// apiError is the documented error envelope MiniMax returns on a non-200
// response.
type apiError struct {
Error struct {
Type string `json:"type"`
Message string `json:"message"`
} `json:"error"`
}
// doJSON issues one request and decodes a 200 response into out. A non-200
// response is parsed as apiError and returned as an error carrying
// MiniMax's own message, so a create/query failure is never reported as a
// bare HTTP status.
func (c *Client) doJSON(ctx context.Context, method, path string, body, out any) error {
var reader io.Reader
if body != nil {
data, err := json.Marshal(body)
if err != nil {
return fmt.Errorf("minimax: encode request: %w", err)
}
reader = bytes.NewReader(data)
}
req, err := http.NewRequestWithContext(ctx, method, strings.TrimRight(c.cfg.BaseURL, "/")+path, reader)
if err != nil {
return fmt.Errorf("minimax: build request: %w", err)
}
req.Header.Set("Authorization", "Bearer "+c.cfg.APIKey)
if body != nil {
req.Header.Set("Content-Type", "application/json")
}
resp, err := c.http.Do(req)
if err != nil {
return fmt.Errorf("minimax: request failed: %w", err)
}
defer resp.Body.Close()
data, err := io.ReadAll(resp.Body)
if err != nil {
return fmt.Errorf("minimax: read response: %w", err)
}
if resp.StatusCode != http.StatusOK {
var apiErr apiError
if err := json.Unmarshal(data, &apiErr); err == nil && apiErr.Error.Message != "" {
return fmt.Errorf("minimax: %s (http %d)", apiErr.Error.Message, resp.StatusCode)
}
return fmt.Errorf("minimax: request failed with http %d: %s", resp.StatusCode, string(data))
}
if err := json.Unmarshal(data, out); err != nil {
return fmt.Errorf("minimax: decode response: %w", err)
}
return nil
}
+231
View File
@@ -0,0 +1,231 @@
package minimax
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
)
// fakeAPI serves a MiniMax API double. create answers with taskID (or
// createStatus/createBody when set); each call to query pops the next
// entry from queryResponses, repeating the last one once exhausted.
type fakeAPI struct {
t *testing.T
createStatus int
createBody string
taskID string
queryResponses []string
queryCalls int
lastAuth string
lastCreateBody map[string]any
}
func (f *fakeAPI) server() *httptest.Server {
return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
f.lastAuth = r.Header.Get("Authorization")
switch {
case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/v2/video_generation"):
var body map[string]any
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
f.t.Fatalf("decode create body: %v", err)
}
f.lastCreateBody = body
if f.createStatus != 0 && f.createStatus != http.StatusOK {
w.WriteHeader(f.createStatus)
_, _ = w.Write([]byte(f.createBody))
return
}
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte(`{"task_id":"` + f.taskID + `"}`))
case r.Method == http.MethodGet && strings.Contains(r.URL.Path, "/v2/query/video_generation/"):
idx := f.queryCalls
if idx >= len(f.queryResponses) {
idx = len(f.queryResponses) - 1
}
f.queryCalls++
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte(f.queryResponses[idx]))
default:
f.t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
}
}))
}
func newTestClient(t *testing.T, api *fakeAPI, pollInterval time.Duration) *Client {
t.Helper()
srv := api.server()
t.Cleanup(srv.Close)
var slept []time.Duration
return New(Config{
Enabled: true,
APIKey: "test-key",
BaseURL: srv.URL,
Timeout: 5 * time.Second,
PollInterval: pollInterval,
// Large relative to any pollInterval used in these tests (including
// the 5s default when pollInterval is 0): Sleep is faked, so this
// costs nothing in real time and just has to outlast however many
// polls a test's queryResponses table needs.
MaxWait: 24 * time.Hour,
Sleep: func(d time.Duration) { slept = append(slept, d) },
})
}
// A submitted job must carry the bearer key and the prompt, and once
// MiniMax reports success the client must hand back the hosted URL, not
// just the fact that it succeeded.
func TestGenerateAndWaitReturnsURLOnSuccess(t *testing.T) {
api := &fakeAPI{t: t, taskID: "task-1", queryResponses: []string{
`{"task":{"id":"task-1","status":"succeeded","content":{"url":"https://cdn.example.com/v.mp4"}}}`,
}}
client := newTestClient(t, api, 0)
url, err := client.GenerateAndWait(context.Background(), GenerateRequest{Prompt: "a cat on a skateboard"})
if err != nil {
t.Fatalf("GenerateAndWait: %v", err)
}
if url != "https://cdn.example.com/v.mp4" {
t.Errorf("url = %q, want the succeeded task's content url", url)
}
if api.lastAuth != "Bearer test-key" {
t.Errorf("Authorization = %q, want Bearer test-key", api.lastAuth)
}
if api.lastCreateBody["content"] == nil {
t.Fatal("create body carried no content")
}
}
// A job that starts queued and moves through running before succeeding
// must be polled repeatedly, not just once.
func TestGenerateAndWaitPollsUntilTerminal(t *testing.T) {
api := &fakeAPI{t: t, taskID: "task-1", queryResponses: []string{
`{"task":{"id":"task-1","status":"queued"}}`,
`{"task":{"id":"task-1","status":"running"}}`,
`{"task":{"id":"task-1","status":"succeeded","content":{"url":"https://cdn.example.com/v.mp4"}}}`,
}}
client := newTestClient(t, api, 0)
url, err := client.GenerateAndWait(context.Background(), GenerateRequest{Prompt: "a cat on a skateboard"})
if err != nil {
t.Fatalf("GenerateAndWait: %v", err)
}
if url != "https://cdn.example.com/v.mp4" {
t.Errorf("url = %q", url)
}
if api.queryCalls != 3 {
t.Errorf("query calls = %d, want 3 (queued, running, succeeded)", api.queryCalls)
}
}
// A failed generation must surface the platform's own error message, not
// just "it failed" -- the model needs enough detail to tell the user
// something useful about why.
func TestGenerateAndWaitReturnsErrorOnFailedStatus(t *testing.T) {
api := &fakeAPI{t: t, taskID: "task-1", queryResponses: []string{
`{"task":{"id":"task-1","status":"failed","error":{"code":"content_policy","message":"prompt rejected"}}}`,
}}
client := newTestClient(t, api, 0)
_, err := client.GenerateAndWait(context.Background(), GenerateRequest{Prompt: "a cat on a skateboard"})
if err == nil {
t.Fatal("expected an error for a failed task")
}
if !strings.Contains(err.Error(), "prompt rejected") {
t.Errorf("error = %v, want it to contain the platform's message", err)
}
}
// A create call that MiniMax itself rejects (bad request, auth, quota,
// content policy, rate limit) must fail before any polling starts, with
// the platform's own description rather than a generic HTTP error.
func TestGenerateReportsCreateFailures(t *testing.T) {
tests := []struct {
name string
status int
body string
wantSubstr string
}{
{
name: "auth",
status: http.StatusUnauthorized,
body: `{"type":"error","error":{"type":"auth_error","message":"invalid API key","http_code":"401"},"request_id":"r1"}`,
wantSubstr: "invalid API key",
},
{
name: "insufficient balance",
status: http.StatusPaymentRequired,
body: `{"type":"error","error":{"type":"balance_error","message":"insufficient balance","http_code":"402"},"request_id":"r2"}`,
wantSubstr: "insufficient balance",
},
{
name: "rate limited",
status: http.StatusTooManyRequests,
body: `{"type":"error","error":{"type":"rate_limit","message":"too many requests","http_code":"429"},"request_id":"r3"}`,
wantSubstr: "too many requests",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
api := &fakeAPI{t: t, createStatus: tt.status, createBody: tt.body}
client := newTestClient(t, api, 0)
_, err := client.GenerateAndWait(context.Background(), GenerateRequest{Prompt: "a cat"})
if err == nil {
t.Fatal("expected an error")
}
if !strings.Contains(err.Error(), tt.wantSubstr) {
t.Errorf("error = %v, want it to contain %q", err, tt.wantSubstr)
}
})
}
}
// A job that never reaches a terminal status must not poll forever: it has
// to give up once MaxWait elapses and say so, rather than hanging the tool
// call (and the whole turn) indefinitely.
func TestGenerateAndWaitTimesOutWithoutRealSleep(t *testing.T) {
responses := make([]string, 100)
for i := range responses {
responses[i] = `{"task":{"id":"task-1","status":"running"}}`
}
api := &fakeAPI{t: t, taskID: "task-1", queryResponses: responses}
srv := api.server()
t.Cleanup(srv.Close)
elapsed := time.Duration(0)
client := New(Config{
Enabled: true,
APIKey: "test-key",
BaseURL: srv.URL,
Timeout: 5 * time.Second,
PollInterval: time.Second,
MaxWait: 10 * time.Second,
Sleep: func(d time.Duration) { elapsed += d },
})
start := time.Now()
_, err := client.GenerateAndWait(context.Background(), GenerateRequest{Prompt: "a cat"})
wallClock := time.Since(start)
if err == nil {
t.Fatal("expected a timeout error")
}
if !strings.Contains(err.Error(), "timed out") {
t.Errorf("error = %v, want a timeout error", err)
}
if wallClock > time.Second {
t.Fatalf("test took %v of real wall-clock time; Sleep was not honored as the delay source", wallClock)
}
if elapsed < 10*time.Second {
t.Errorf("simulated elapsed = %v, want at least MaxWait (10s)", elapsed)
}
}
+92
View File
@@ -0,0 +1,92 @@
package minimax
import (
"context"
"fmt"
"strings"
"github.com/samcharles93/archie-core/internal/tools"
)
// ToolName is the registry name of the video-generation tool.
const ToolName = "generate_video"
// Tool builds the registry entry for cfg, or nil when disabled -- the
// same "withdraw entirely rather than advertise a broken capability"
// reasoning webfetch.Tool documents.
//
// Classified ClassMutating, not RequiresApproval: it creates a hosted
// resource and spends real API credits, which is a mutating action, but
// gating every call behind human approval would make the tool unusable
// for its purpose. Revisit if usage shows this needs a spend guard.
func Tool(cfg Config) *tools.ToolEntry {
if !cfg.Enabled {
return nil
}
client := New(cfg)
return &tools.ToolEntry{
Name: ToolName,
Toolset: "media",
Description: "Generate a short video from a text prompt using MiniMax. " +
"Generation runs synchronously and can take several minutes; the call " +
"blocks until the video is ready or generation fails. Returns a hosted " +
"URL for the finished video.",
Classification: tools.ClassMutating,
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"prompt": map[string]any{
"type": "string",
"description": "Description of the video to generate. Up to 7000 characters.",
},
"resolution": map[string]any{
"type": "string",
"enum": []any{"768P", "2K"},
"description": "Video resolution. Defaults to 768P.",
},
"duration": map[string]any{
"type": "integer",
"minimum": 4,
"maximum": 15,
"description": "Clip length in seconds, 4-15. Defaults to 6.",
},
"ratio": map[string]any{
"type": "string",
"enum": []any{"adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"},
"description": "Aspect ratio. Defaults to adaptive.",
},
},
"required": []any{"prompt"},
},
Handler: func(ctx context.Context, input map[string]any) (any, error) {
prompt, _ := input["prompt"].(string)
if strings.TrimSpace(prompt) == "" {
return nil, fmt.Errorf("%s: prompt is required", ToolName)
}
resolution, _ := input["resolution"].(string)
ratio, _ := input["ratio"].(string)
duration := 0
if d, ok := input["duration"].(float64); ok {
duration = int(d)
}
url, err := client.GenerateAndWait(ctx, GenerateRequest{
Prompt: prompt,
Resolution: resolution,
Duration: duration,
Ratio: ratio,
})
if err != nil {
return nil, fmt.Errorf("%s: %w", ToolName, err)
}
return tools.MultimodalResult{
IsMultimodal: true,
Summary: "Generated a video from the prompt.",
URLs: []tools.MediaRef{{Type: "video", URL: url}},
}, nil
},
}
}
+122
View File
@@ -0,0 +1,122 @@
package minimax
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/tools"
)
// Disabled must withdraw the tool entirely: an advertised tool that always
// fails costs the model a wasted round trip to discover it doesn't work,
// the same reasoning webfetch.Tool documents for its own Enabled check.
func TestToolReturnsNilWhenDisabled(t *testing.T) {
if entry := Tool(Config{Enabled: false}); entry != nil {
t.Fatal("expected a nil entry when disabled")
}
}
func TestToolHasRequiredPromptSchema(t *testing.T) {
entry := Tool(Config{Enabled: true, APIKey: "k"})
if entry == nil {
t.Fatal("expected a non-nil entry")
}
if entry.Name != ToolName {
t.Errorf("Name = %q, want %q", entry.Name, ToolName)
}
required, _ := entry.Schema["required"].([]any)
if len(required) != 1 || required[0] != "prompt" {
t.Errorf("required = %v, want [prompt]", required)
}
}
// A missing prompt must be rejected before any network call, matching
// webfetch's own required-field check.
func TestToolHandlerRejectsEmptyPrompt(t *testing.T) {
entry := Tool(Config{Enabled: true, APIKey: "k"})
if _, err := entry.Handler(context.Background(), map[string]any{}); err == nil {
t.Fatal("expected an error for a missing prompt")
}
}
// The handler's success path must produce a tools.MultimodalResult carrying
// the video as a URLs entry: that is the shared envelope the gateway wiring
// (cmd/archied) knows how to turn into a delivered attachment. Returning a
// bare string here would leave the video undeliverable no matter how good
// the rest of the pipeline is.
func TestToolHandlerReturnsMultimodalResultOnSuccess(t *testing.T) {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
switch r.Method {
case http.MethodPost:
_, _ = w.Write([]byte(`{"task_id":"task-1"}`))
default:
_, _ = w.Write([]byte(`{"task":{"id":"task-1","status":"succeeded","content":{"url":"https://cdn.example.com/v.mp4"}}}`))
}
}))
t.Cleanup(srv.Close)
entry := Tool(Config{
Enabled: true,
APIKey: "k",
BaseURL: srv.URL,
Timeout: 5 * time.Second,
PollInterval: 0,
MaxWait: time.Hour,
Sleep: func(time.Duration) {},
})
out, err := entry.Handler(context.Background(), map[string]any{"prompt": "a cat on a skateboard"})
if err != nil {
t.Fatalf("Handler: %v", err)
}
data, err := json.Marshal(out)
if err != nil {
t.Fatalf("marshal handler output: %v", err)
}
var result tools.MultimodalResult
if err := json.Unmarshal(data, &result); err != nil {
t.Fatalf("handler output is not a MultimodalResult: %v", err)
}
if !result.IsMultimodal {
t.Error("expected IsMultimodal = true")
}
if len(result.URLs) != 1 || result.URLs[0].Type != "video" || result.URLs[0].URL != "https://cdn.example.com/v.mp4" {
t.Errorf("URLs = %+v, want [{video https://cdn.example.com/v.mp4}]", result.URLs)
}
}
// A generation failure must surface as a handler error, not a
// MultimodalResult with no URLs: a silently empty result reads to the
// model as "it worked but produced nothing" rather than "it failed."
func TestToolHandlerReturnsErrorOnGenerationFailure(t *testing.T) {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
switch r.Method {
case http.MethodPost:
_, _ = w.Write([]byte(`{"task_id":"task-1"}`))
default:
_, _ = w.Write([]byte(`{"task":{"id":"task-1","status":"failed","error":{"message":"prompt rejected"}}}`))
}
}))
t.Cleanup(srv.Close)
entry := Tool(Config{
Enabled: true,
APIKey: "k",
BaseURL: srv.URL,
Timeout: 5 * time.Second,
PollInterval: 0,
MaxWait: time.Hour,
Sleep: func(time.Duration) {},
})
if _, err := entry.Handler(context.Background(), map[string]any{"prompt": "a cat"}); err == nil {
t.Fatal("expected an error")
}
}
+15
View File
@@ -22,4 +22,19 @@ type MultimodalResult struct {
// Files lists the full paths written under SubdirHint, in the order
// the source content blocks appeared.
Files []string `json:"files,omitempty"`
// URLs lists media that lives at a remote, already-hosted URL rather
// than local bytes -- a generation API's result, for example, which
// has nowhere to go in Files: there is no SubdirHint to write it under
// because nothing was downloaded.
URLs []MediaRef `json:"urls,omitempty"`
}
// MediaRef is one piece of remote-hosted media within a MultimodalResult.
type MediaRef struct {
// Type is "image", "video", "audio", or "document" -- the same
// vocabulary gateway.MediaAttachment.Type uses, so a caller can build
// one directly from this without translation.
Type string `json:"type"`
// URL is where the media is hosted.
URL string `json:"url"`
}
+25
View File
@@ -47,4 +47,29 @@ func TestMultimodalResultOmitsEmptyOptionalFields(t *testing.T) {
if _, ok := got["files"]; ok {
t.Error("files should be omitted when empty")
}
if _, ok := got["urls"]; ok {
t.Error("urls should be omitted when empty")
}
}
// A tool whose media lives at a remote URL (a generation API's hosted
// result) rather than local bytes has nowhere to put it in Files, which is
// always a path under SubdirHint. URLs is that case.
func TestMultimodalResultURLsRoundTrip(t *testing.T) {
r := MultimodalResult{
IsMultimodal: true,
Summary: "generated a video",
URLs: []MediaRef{{Type: "video", URL: "https://example.com/v.mp4"}},
}
data, err := json.Marshal(r)
if err != nil {
t.Fatal(err)
}
var got MultimodalResult
if err := json.Unmarshal(data, &got); err != nil {
t.Fatal(err)
}
if len(got.URLs) != 1 || got.URLs[0].Type != "video" || got.URLs[0].URL != "https://example.com/v.mp4" {
t.Errorf("URLs round-trip = %+v, want [{video https://example.com/v.mp4}]", got.URLs)
}
}
+15
View File
@@ -254,6 +254,21 @@ func (s chatStreamSink) ToolCall(event gateway.ToolCallEvent) {
})
}
// Media has no inline rendering path on the dashboard yet (see
// archie-core-1786748942243-6-f109697e), so it degrades to a link in the
// delta stream -- the same fallback Telegram's liveReply uses when its own
// SendMedia call fails. An attachment with no URL has nothing to link to
// and is skipped rather than emitting an empty line.
func (s chatStreamSink) Media(event gateway.MediaEvent) {
if event.Attachment.URL == "" {
return
}
s.write(chatStreamEvent{
Type: "delta",
Text: "\n\n📎 " + event.Attachment.Type + ": " + event.Attachment.URL,
})
}
// chatShowToolCalls reports config.ChatConfig.ShowToolCalls, the one setting
// shared by every chat channel. Off (the default) when Cfg is nil, matching
// the field's own off-by-default doc comment: a dashboard embedded without
+66
View File
@@ -679,6 +679,72 @@ func TestChatStreamReportsToolCalls(t *testing.T) {
}
}
// The dashboard has no inline media rendering path yet (see
// archie-core-1786748942243-6-f109697e), so a MediaEvent has to degrade to
// a link in the text stream rather than being silently dropped -- the same
// fallback Telegram's liveReply uses when SendMedia itself fails.
func TestChatStreamRendersMediaAsALinkFallback(t *testing.T) {
stream := func(_ context.Context, _ gateway.Message, turn gateway.TurnStream) (string, error) {
turn.Delta("here you go")
turn.Media(gateway.MediaEvent{
ToolName: "video_gen",
Attachment: gateway.MediaAttachment{Type: "video", URL: "https://example.com/v.mp4"},
})
return "here you go", nil
}
server, sessions := chatTestServer(t)
server.Chat.Router.LLMStream = stream
saveWebSession(t, sessions, "web-1")
req := httptest.NewRequestWithContext(context.Background(), http.MethodPost, "/api/chat/stream",
strings.NewReader(`{"channel_id":"browser-web-1","text":"make me a video"}`))
req.Header.Set("Content-Type", "application/json")
res := httptest.NewRecorder()
server.Handler().ServeHTTP(res, req)
if res.Code != http.StatusOK {
t.Fatalf("status = %d, body = %s", res.Code, res.Body)
}
var joined string
for _, ev := range parseChatSSE(t, res.Body.String()) {
if ev.Type == "delta" {
joined += ev.Text
}
}
if !strings.Contains(joined, "https://example.com/v.mp4") {
t.Fatalf("delta stream = %q, want it to contain the asset URL", joined)
}
}
// An event with no URL has nothing to link to, so it must not add an
// empty or broken-looking line to the transcript.
func TestChatStreamSkipsMediaWithNoURL(t *testing.T) {
stream := func(_ context.Context, _ gateway.Message, turn gateway.TurnStream) (string, error) {
turn.Media(gateway.MediaEvent{ToolName: "video_gen", Attachment: gateway.MediaAttachment{Type: "video"}})
return "", nil
}
server, sessions := chatTestServer(t)
server.Chat.Router.LLMStream = stream
saveWebSession(t, sessions, "web-1")
req := httptest.NewRequestWithContext(context.Background(), http.MethodPost, "/api/chat/stream",
strings.NewReader(`{"channel_id":"browser-web-1","text":"make me a video"}`))
req.Header.Set("Content-Type", "application/json")
res := httptest.NewRecorder()
server.Handler().ServeHTTP(res, req)
if res.Code != http.StatusOK {
t.Fatalf("status = %d, body = %s", res.Code, res.Body)
}
for _, ev := range parseChatSSE(t, res.Body.String()) {
if ev.Type == "delta" && ev.Text != "" {
t.Fatalf("got a delta for a URL-less media event: %q", ev.Text)
}
}
}
// config.ChatConfig.ShowToolCalls is off by default and shared by every chat
// channel: an operator who left it unset (or explicitly turned it off) must
// see no tool activity on the dashboard, not just in Telegram. Previously the