feat(tui): open generated files and reports in a terminal viewer

Add a clickable "Files generated" list in the chat transcript with a
full-screen file viewer (Esc to return). Wire Studio artifact/report_marker
SSE events and session history artifacts through the platform backend, and
fetch content via GET /api/studio/artifacts/content.

Author: rschardosin

docs/architecture/terminal-app.md

@@ -103,6 +103,7 @@ AdaptiveColor cursor-line backgrounds that break dark alt-screen UIs).
 | Tool activity | `pkg/tui/render.ActivitySummary` + `StatsFromSteps` (`+N/−M`); click-to-expand reveals **raw request args and response JSON** (not file diffs) |
 | Network authorization | Inline transcript notice plus a focused approval card for OpenShell proxy denials; `enter`/`y` allows the blocked host, `b` allows the suggested broader pattern, and `n`/`esc` denies |
 | File diffs | **Main-thread** `ItemFileDiff` dual-gutter editor view (`old`/`new` line numbers + ± content) on successful `edit_file`/`write_file`. Prefers `verification_context`; falls back to args |
+| Generated files / reports | `artifact` SSE events render as a compact “Files generated” list in the transcript. Clicking a file opens a full-screen file viewer; `Esc` returns to the main chat. Markdown artifacts render through the same terminal markdown renderer as agent responses, while other extensions render as scrollable raw/code content with line numbers. |
 
 Streaming: unclosed fences render as incomplete code blocks (header shows `…`).
 
@@ -149,6 +150,7 @@ Approvals and denials call the network-grant REST endpoints directly instead of
 - `ctrl+l` or `/sessions` — list sessions, `enter` resume, `d` delete with confirmation, `n` new, `esc` close
 - `ctrl+n` or `/new` — clear local session id; next message creates a new server session
 - Click a tool activity block to expand/collapse detailed execution rows; `ctrl+o` toggles the latest activity
+- Click a generated file row to open it in the terminal file viewer; `Esc` returns to the chat thread
 - Drag across transcript text to select it; releasing the mouse automatically copies the selected plain text to the system clipboard
 - `astonish chat --resume <id>` — loads history via `GET /api/studio/sessions/{id}` on open
 

docs/website/docs/cli/chat.md

@@ -88,6 +88,10 @@ Pasting an image from the clipboard inserts `[image #1]` (then `#2`, `#3`, …).
 
 On Linux, image paste requires `wl-paste` (Wayland) or `xclip` (X11) on `PATH`. On macOS, the system pasteboard is used directly.
 
+## Generated files and reports
+
+When an agent creates files, the terminal transcript shows a compact **Files generated** list. Click a file row to open it in a full-screen viewer; press `Esc` to return to the main chat thread. Markdown files and reports render with formatted headings, lists, tables, and code blocks. Other file types open as scrollable raw/code content with line numbers.
+
 ## In-Session Commands
 
 While in an active chat session, type `/` to access these commands:

pkg/client/api.go

@@ -2,6 +2,7 @@ package client
 
 import (
 	"fmt"
+	"io"
 	"net/http"
 	"net/url"
 )
@@ -63,9 +64,20 @@ type SessionDetail struct {
 	CreatedAt    string          `json:"createdAt"`
 	UpdatedAt    string          `json:"updatedAt"`
 	Messages     []StudioMessage `json:"messages"`
+	Artifacts    []ArtifactInfo  `json:"artifacts,omitempty"`
 	TotalUsage   *UsageSummary   `json:"totalUsage,omitempty"`
 }
 
+// ArtifactInfo describes a generated file returned by the Studio session API.
+type ArtifactInfo struct {
+	Path        string `json:"path"`
+	FileName    string `json:"fileName"`
+	FileType    string `json:"fileType"`
+	ToolName    string `json:"toolName"`
+	IsReport    bool   `json:"isReport,omitempty"`
+	ReportTitle string `json:"reportTitle,omitempty"`
+}
+
 // GetSessionDetail returns typed session history for the terminal chat app.
 func (c *Client) GetSessionDetail(id string) (*SessionDetail, error) {
 	var detail SessionDetail
@@ -238,6 +250,28 @@ func (c *Client) SendChatMessage(req *ChatRequest) (*SSEStream, error) {
 	return c.SSE("POST", "/api/studio/chat", req)
 }
 
+// GetArtifactContent returns the plain-text content for a generated file artifact.
+func (c *Client) GetArtifactContent(path, sessionID string) (string, error) {
+	params := url.Values{}
+	params.Set("path", path)
+	if sessionID != "" {
+		params.Set("session", sessionID)
+	}
+	resp, err := c.Do("GET", "/api/studio/artifacts/content?"+params.Encode(), nil)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		return "", parseErrorResponse(resp)
+	}
+	data, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("read artifact content: %w", err)
+	}
+	return string(data), nil
+}
+
 // NetworkDenial describes a blocked outbound connection returned by Studio.
 type NetworkDenial struct {
 	ChunkID        string `json:"chunk_id"`

pkg/launcher/tui_chat.go

@@ -322,6 +322,24 @@ func (b *platformBackend) SetModelPin(ctx context.Context, provider, model strin
 	return effP, effM, nil
 }
 
+func (b *platformBackend) ReadArtifactContent(ctx context.Context, sessionID, path string) (backend.ArtifactContent, error) {
+	_ = ctx
+	path = strings.TrimSpace(path)
+	if path == "" {
+		return backend.ArtifactContent{}, fmt.Errorf("artifact path required")
+	}
+	if sessionID == "" {
+		b.mu.Lock()
+		sessionID = b.sessionID
+		b.mu.Unlock()
+	}
+	content, err := b.client.GetArtifactContent(path, sessionID)
+	if err != nil {
+		return backend.ArtifactContent{}, err
+	}
+	return backend.ArtifactContent{Path: path, Content: content}, nil
+}
+
 func (b *platformBackend) NewSession() {
 	b.mu.Lock()
 	b.sessionID = ""
@@ -382,7 +400,7 @@ func (b *platformBackend) loadHistory(ctx context.Context, id string) ([]backend
 	_ = detail.Title
 	b.usage = usageFromSessionDetail(detail)
 	b.mu.Unlock()
-	return studioMessagesToHistory(detail.Messages), nil
+	return studioDetailToHistory(detail), nil
 }
 
 func usageFromSessionDetail(detail *client.SessionDetail) *events.Usage {
@@ -430,6 +448,21 @@ func addUsage(total, delta *events.Usage) *events.Usage {
 	return total
 }
 
+func studioDetailToHistory(detail *client.SessionDetail) []backend.HistoryEntry {
+	if detail == nil {
+		return nil
+	}
+	out := studioMessagesToHistory(detail.Messages)
+	for _, a := range detail.Artifacts {
+		artifact := artifactFromClient(a)
+		if artifact.Path == "" {
+			continue
+		}
+		out = append(out, backend.HistoryEntry{Kind: "artifact", Text: artifact.Path, Artifact: &artifact})
+	}
+	return out
+}
+
 func studioMessagesToHistory(msgs []client.StudioMessage) []backend.HistoryEntry {
 	out := make([]backend.HistoryEntry, 0, len(msgs))
 	for _, m := range msgs {
@@ -471,6 +504,17 @@ func studioMessagesToHistory(msgs []client.StudioMessage) []backend.HistoryEntry
 	return out
 }
 
+func artifactFromClient(a client.ArtifactInfo) events.Artifact {
+	return events.Artifact{
+		Path:        a.Path,
+		FileName:    a.FileName,
+		FileType:    a.FileType,
+		ToolName:    a.ToolName,
+		IsReport:    a.IsReport,
+		ReportTitle: a.ReportTitle,
+	}
+}
+
 func (b *platformBackend) RunTurn(ctx context.Context, message string, opts backend.TurnOptions) (<-chan events.Event, error) {
 	b.mu.Lock()
 	if b.closed {
@@ -752,21 +796,52 @@ func mapSSEToEvents(sev *client.SSEEvent, debug bool) []events.Event {
 				}
 			}
 		}
+	case "report_marker":
+		var payload struct {
+			Path  string `json:"path"`
+			Title string `json:"title"`
+		}
+		if json.Unmarshal(data, &payload) == nil && payload.Path != "" {
+			artifact := events.Artifact{Path: payload.Path, IsReport: true, ReportTitle: payload.Title}
+			return []events.Event{{
+				Kind:     events.KindReportMarker,
+				Text:     payload.Path,
+				Artifact: &artifact,
+				Meta:     map[string]any{"path": payload.Path, "title": payload.Title},
+			}}
+		}
 	case "artifact":
 		var payload struct {
-			Path     string `json:"path"`
-			ToolName string `json:"tool_name"`
-			FileName string `json:"fileName"`
+			Path        string `json:"path"`
+			ToolName    string `json:"tool_name"`
+			ToolName2   string `json:"toolName"`
+			FileName    string `json:"fileName"`
+			FileType    string `json:"fileType"`
+			IsReport    bool   `json:"isReport"`
+			ReportTitle string `json:"reportTitle"`
 		}
 		if json.Unmarshal(data, &payload) == nil {
 			path := payload.Path
 			if path == "" {
 				path = payload.FileName
 			}
+			toolName := payload.ToolName
+			if toolName == "" {
+				toolName = payload.ToolName2
+			}
+			artifact := events.Artifact{
+				Path:        path,
+				FileName:    payload.FileName,
+				FileType:    payload.FileType,
+				ToolName:    toolName,
+				IsReport:    payload.IsReport,
+				ReportTitle: payload.ReportTitle,
+			}
 			return []events.Event{{
-				Kind: events.KindArtifact,
-				Text: path,
-				Meta: map[string]any{"path": path, "tool": payload.ToolName},
+				Kind:     events.KindArtifact,
+				Text:     path,
+				Artifact: &artifact,
+				Meta:     map[string]any{"path": path, "tool": toolName},
 			}}
 		}
 	case "error":

pkg/launcher/tui_chat_test.go

@@ -88,6 +88,46 @@ func TestMapSSEToEvents_SoftDegrade(t *testing.T) {
 	}
 }
 
+func TestMapSSEToEvents_ArtifactMetadata(t *testing.T) {
+	evs := mapSSEToEvents(&client.SSEEvent{
+		Type: "artifact",
+		Data: `{"path":"/tmp/report.md","fileName":"report.md","fileType":"Markdown","toolName":"write_file","isReport":true,"reportTitle":"Quarterly Report"}`,
+	}, false)
+	if len(evs) != 1 || evs[0].Kind != events.KindArtifact || evs[0].Artifact == nil {
+		t.Fatalf("artifact: %+v", evs)
+	}
+	artifact := evs[0].Artifact
+	if artifact.Path != "/tmp/report.md" || artifact.FileName != "report.md" || artifact.FileType != "Markdown" || !artifact.IsReport || artifact.ReportTitle != "Quarterly Report" {
+		t.Fatalf("artifact metadata: %+v", artifact)
+	}
+}
+
+func TestMapSSEToEvents_ReportMarker(t *testing.T) {
+	evs := mapSSEToEvents(&client.SSEEvent{
+		Type: "report_marker",
+		Data: `{"path":"/tmp/report.md","title":"Quarterly Report"}`,
+	}, false)
+	if len(evs) != 1 || evs[0].Kind != events.KindReportMarker || evs[0].Artifact == nil {
+		t.Fatalf("report marker: %+v", evs)
+	}
+	if evs[0].Artifact.Path != "/tmp/report.md" || !evs[0].Artifact.IsReport || evs[0].Artifact.ReportTitle != "Quarterly Report" {
+		t.Fatalf("report marker artifact: %+v", evs[0].Artifact)
+	}
+}
+
+func TestStudioDetailToHistoryIncludesArtifacts(t *testing.T) {
+	hist := studioDetailToHistory(&client.SessionDetail{
+		Messages:  []client.StudioMessage{{Type: "agent", Content: "done"}},
+		Artifacts: []client.ArtifactInfo{{Path: "/tmp/report.md", FileName: "report.md", FileType: "Markdown", IsReport: true}},
+	})
+	if len(hist) != 2 {
+		t.Fatalf("history len=%d want 2: %+v", len(hist), hist)
+	}
+	if hist[1].Kind != "artifact" || hist[1].Artifact == nil || hist[1].Artifact.Path != "/tmp/report.md" {
+		t.Fatalf("artifact history entry: %+v", hist[1])
+	}
+}
+
 func TestMapSSEToEvents_SkipToolBoxFrame(t *testing.T) {
 	evs := mapSSEToEvents(&client.SSEEvent{
 		Type: "text",