From 19c9002c1906f0b184eb2f45b84ebf421465d806 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 9 Sep 2026 23:33:38 +1000 Subject: [PATCH] feat(gateway): add session_transcript tool for full JSON export --- internal/gateway/session_tools.go | 92 ++++++++++++++++++++++++++ internal/gateway/session_tools_test.go | 54 +++++++++++++-- 2 files changed, 142 insertions(+), 4 deletions(-) diff --git a/internal/gateway/session_tools.go b/internal/gateway/session_tools.go index 5792e0869..7ca9b88c2 100644 --- a/internal/gateway/session_tools.go +++ b/internal/gateway/session_tools.go @@ -2,7 +2,9 @@ package gateway import ( "context" + "encoding/json" "fmt" + "os" "slices" "strings" "time" @@ -24,6 +26,9 @@ const ( // rendered in command replies and the dashboard; an unbounded one would let // a model bloat every surface that shows it. maxSessionTitleLen = 80 + + // maxSessionTranscriptLimit bounds the number of messages in a transcript export. + maxSessionTranscriptLimit = 10000 ) // ChatSessionSummary is the per-session view the session tools return. It is @@ -87,6 +92,7 @@ func SessionTools(store SessionStore, tracker *sessionTracker, platform string, channelID := msg.ConversationID.ChannelID var entries []tools.ToolEntry entries = append(entries, sessionListTool(store, platform, channelID)) + entries = append(entries, sessionTranscriptTool(store, platform, channelID)) if tracker != nil { entries = append(entries, sessionResumeTool(store, tracker, platform, channelID, msg)) entries = append(entries, sessionDeleteTool(store, tracker, platform, channelID)) @@ -320,3 +326,89 @@ func sessionDeleteTool(store SessionStore, tracker *sessionTracker, platform, ch func sessionListLimit(input map[string]any) int { return tools.ListLimit(input, defaultSessionListLimit, maxSessionListLimit) } + +// sessionTranscriptResult is what session_transcript returns. +type sessionTranscriptResult struct { + FilePath string `json:"file_path"` + SizeBytes int64 `json:"size_bytes"` + MessageCount int `json:"message_count"` + SessionID string `json:"session_id"` + Message string `json:"message"` +} + +func sessionTranscriptTool(store SessionStore, platform, channelID string) tools.ToolEntry { + return tools.ToolEntry{ + Name: "session_transcript", + Toolset: "session", + Description: "Export a complete session transcript as a JSON file. " + + "Use this when an operator wants to review, archive, or share a full conversation " + + "including all messages, tool calls with their arguments, and tool results. " + + "The export is written to a file on the local filesystem and delivered via " + + "send_file. All data is included verbatim with no truncation.", + Classification: tools.ClassIdempotent, + Schema: tools.JSONSchema{ + "type": "object", + "properties": map[string]any{ + "session_id": map[string]any{ + "type": "string", + "description": "The session ID or a unique prefix, same as session_list.", + }, + }, + "required": []any{"session_id"}, + }, + Handler: func(ctx context.Context, input map[string]any) (any, error) { + ref := strings.TrimSpace(asString(input["session_id"])) + if ref == "" { + return nil, fmt.Errorf("session_transcript: session_id is required") + } + + sessions, err := store.GetByChannel(ctx, platform, channelID) + if err != nil { + return nil, fmt.Errorf("session_transcript: %w", err) + } + target, ambiguous := resolveSessionRef(sessions, ref) + switch { + case ambiguous: + return nil, fmt.Errorf("session_transcript: multiple sessions match %q; be more specific", ref) + case target == nil: + return nil, fmt.Errorf("session_transcript: no session matching %q", ref) + } + + messages, err := store.RecentMessages(ctx, target.SessionID, maxSessionTranscriptLimit) + if err != nil { + return nil, fmt.Errorf("session_transcript: %w", err) + } + + // Serialize to JSON + data, err := json.MarshalIndent(messages, "", " ") + if err != nil { + return nil, fmt.Errorf("session_transcript: %w", err) + } + + // Write to temp file + f, err := os.CreateTemp("", "transcript-*.json") + if err != nil { + return nil, fmt.Errorf("session_transcript: %w", err) + } + defer f.Close() + + if _, err := f.Write(data); err != nil { + return nil, fmt.Errorf("session_transcript: %w", err) + } + + stat, err := f.Stat() + if err != nil { + return nil, fmt.Errorf("session_transcript: %w", err) + } + + return sessionTranscriptResult{ + FilePath: f.Name(), + SizeBytes: stat.Size(), + MessageCount: len(messages), + SessionID: target.SessionID, + Message: fmt.Sprintf("Transcript export written to %s (%d bytes, %d messages). Use send_file to deliver it.", + f.Name(), stat.Size(), len(messages)), + }, nil + }, + } +} diff --git a/internal/gateway/session_tools_test.go b/internal/gateway/session_tools_test.go index a76546b53..04ea3690c 100644 --- a/internal/gateway/session_tools_test.go +++ b/internal/gateway/session_tools_test.go @@ -259,8 +259,8 @@ func TestSessionToolClassifications(t *testing.T) { store := newFakeSessionStore() tr := newSessionTracker(store) entries := SessionTools(store, tr, "test-gw", inbound("chat-1", "").Message) - if len(entries) != 4 { - t.Fatalf("got %d tools, want 4", len(entries)) + if len(entries) != 5 { + t.Fatalf("got %d tools, want 5", len(entries)) } tests := []struct { @@ -270,6 +270,7 @@ func TestSessionToolClassifications(t *testing.T) { approval bool }{ {name: "session_list", idempotent: true}, + {name: "session_transcript", idempotent: true}, {name: "session_resume", mutating: true}, {name: "session_title", mutating: true}, {name: "session_delete", mutating: true, approval: true}, @@ -310,8 +311,8 @@ func TestSessionToolNilTrackerOmitsTrackerTools(t *testing.T) { for _, e := range entries { names = append(names, e.Name) } - if len(entries) != 2 { - t.Fatalf("got %d tools (%v), want the 2 store-only tools", len(entries), names) + if len(entries) != 3 { + t.Fatalf("got %d tools (%v), want the 3 store-only tools", len(entries), names) } for _, name := range names { switch name { @@ -320,3 +321,48 @@ func TestSessionToolNilTrackerOmitsTrackerTools(t *testing.T) { } } } + +func TestSessionToolTranscriptExportsSession(t *testing.T) { + store := newFakeSessionStore() + tr := newSessionTracker(store) + entry := sessionTool(t, SessionTools(store, tr, "test-gw", inbound("chat-1", "").Message), "session_transcript") + + seedSessionAt(store, "transcript-target", "target session", time.Now()) + + // Add some messages + now := time.Now() + for i := range 5 { + msg := messaging.Message{ + ID: messaging.MessageID(fmt.Sprintf("msg-%d", i)), + ConversationID: messaging.ConversationID{ChannelID: "chat-1", ThreadID: "thread-1"}, + SourceID: fmt.Sprintf("src-%d", i), + Role: messaging.RoleUser, + Text: fmt.Sprintf("User message %d", i), + At: now.Add(time.Duration(i) * time.Minute), + } + if err := store.SaveMessage(context.Background(), "transcript-target", msg); err != nil { + t.Fatalf("SaveMessage: %v", err) + } + } + + out, err := entry.Handler(context.Background(), map[string]any{"session_id": "transcript-target"}) + if err != nil { + t.Fatalf("handler: %v", err) + } + result, ok := out.(sessionTranscriptResult) + if !ok { + t.Fatalf("handler returned %T, want sessionTranscriptResult", out) + } + if result.SessionID != "transcript-target" { + t.Errorf("session_id = %q, want transcript-target", result.SessionID) + } + if result.MessageCount != 5 { + t.Errorf("message_count = %d, want 5", result.MessageCount) + } + if result.SizeBytes <= 0 { + t.Errorf("size_bytes = %d, want > 0", result.SizeBytes) + } + if result.FilePath == "" { + t.Error("file_path is empty") + } +}