WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

2026-09-22 16:19:06 +08:00
commit f7fc992f57
3929 changed files with 1006607 additions and 0 deletions
@@ -0,0 +1,358 @@
+// Package chat implements `weknora chat <text>` - the streaming RAG answer
+// entry point.
+//
+// Three output modes share a single SDK call:
+//
+//   - JSON mode (--format json, the default): buffer a bounded projection of
+//     the stream into one success envelope. The default projection contains
+//     answer events only; --reference adds indexed citations and --verbose
+//     adds reasoning, tools, and lifecycle frames.
+//
+//   - Text mode (--format text): render the same projection as JSON
+//     directly to iostreams.IO.Out as it arrives.
+//
+//   - NDJSON mode (--format ndjson): inject a CLI "init" event at stream
+//     head, then pass through every SDK event verbatim as NDJSON lines —
+//     the raw protocol trace, for debugging / advanced consumers.
+//
+// The SDK's KnowledgeQAStream callback contract is invoked sequentially on
+// one goroutine, so no mode needs locking. The runChat core takes a
+// ChatService interface so tests inject a fake without standing up a real
+// SSE server.
+package chat
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	"github.com/Tencent/WeKnora/cli/internal/output"
+	"github.com/Tencent/WeKnora/cli/internal/sse"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// chatFields enumerates the fields surfaced for `--jq` projection discovery
+// on `chat`: the json object's data fields + the raw SDK event vocabulary
+// used by --format ndjson.
+var chatFields = []string{
+	"events", "session_id", "assistant_message_id", "kb_id", "query",
+	// NDJSON init + SDK event fields.
+	"type", "kb_id", "profile", "response_type", "content", "done", "knowledge_references", "data",
+}
+
+type Options struct {
+	Query     string
+	KBID      string
+	SessionID string
+	// Reference adds bounded kb_id/chunk_id reference events to JSON/text.
+	Reference bool
+	// Verbose surfaces the projected execution trace in JSON/text,
+	// including reasoning, tools, and lifecycle events.
+	// NDJSON is always raw and is unaffected by presentation flags.
+	Verbose bool
+}
+
+// ChatService is the narrow SDK surface this command depends on. *sdk.Client
+// satisfies it; tests substitute a fake. Compile-time check is at the bottom
+// of this file.
+type ChatService interface {
+	CreateSession(ctx context.Context, req *sdk.CreateSessionRequest) (*sdk.Session, error)
+	KnowledgeQAStream(ctx context.Context, sessionID string, req *sdk.KnowledgeQARequest, cb func(*sdk.StreamResponse) error, opts ...sdk.ResourceURLOptions) error
+}
+
+// NewCmd builds `weknora chat <text>`.
+func NewCmd(f *cmdutil.Factory) *cobra.Command {
+	opts := &Options{}
+	cmd := &cobra.Command{
+		Use:   `chat "<text>"`,
+		Short: "Ask a streaming RAG question against a knowledge base",
+		Long: `Send a query to the WeKnora knowledge-chat endpoint and stream the
+answer back. By default a fresh session is created on first invocation; pass
+--session to continue an existing conversation.
+
+Modes:
+  --format json (default):       one JSON envelope with answer events
+  --format text:                 live human-readable answer stream
+  --format ndjson:               raw NDJSON event stream — init line (session_id,
+                                 kb_id) then SDK events verbatim. Debug / advanced.
+
+Pass --reference to include bounded kb_id/chunk_id reference indexes. Pass
+--verbose to include reasoning, tool activity, and lifecycle frames. Combine
+both flags for the complete projected stream.`,
+		Example: `  weknora chat "What is RRF?" --kb a32a63ff-fb36-4874-bcaa-30f48570a694
+  weknora chat "Summarise this design doc" --kb my-kb --format json
+  weknora chat "Continue?" --session sess_abc`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(c *cobra.Command, args []string) error {
+			opts.Query = strings.TrimSpace(args[0])
+			if opts.Query == "" {
+				return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty")
+			}
+			fopts, err := cmdutil.CheckFormatFlag(c)
+			if err != nil {
+				return err
+			}
+			fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
+			kbID, err := f.ResolveKB(c)
+			if err != nil {
+				return err
+			}
+			opts.KBID = kbID
+			cli, err := f.Client()
+			if err != nil {
+				return err
+			}
+			return runChat(c.Context(), opts, fopts, cli)
+		},
+	}
+	cmdutil.AddKBFlag(cmd)
+	cmd.Flags().StringVar(&opts.SessionID, "session", "", "Continue an existing chat session (skip auto-create)")
+	cmd.Flags().BoolVar(&opts.Reference, "reference", false, "Include indexed references in JSON/text output")
+	cmd.Flags().BoolVar(&opts.Verbose, "verbose", false, "Include reasoning, tools, and lifecycle events in JSON/text output")
+	cmdutil.AddFormatFlag(cmd, chatFields...)
+	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
+		UsedFor:       "Ask a RAG question against a knowledge base. Default JSON returns a bounded answer-event projection. --reference adds indexed citations; --verbose adds reasoning, tools, and lifecycle events. --format ndjson streams raw SDK events; --format text renders the selected events live.",
+		RequiredFlags: []string{"<text> (positional)", "--kb"},
+		Examples: []string{
+			`weknora chat "What is RRF?" --kb kb_abc`,
+			`weknora chat "What is RRF?" --kb kb_abc --jq '[.data.events[].content] | join("")'`,
+		},
+		Output: "Default --format json: {ok,data:{events:[answer...],session_id,kb_id,query}}. --reference adds kb_id/chunk_id reference events; --verbose adds execution events. --format ndjson remains raw.",
+	})
+	return cmd
+}
+
+// runChat is the testable core: validate, ensure a session, dispatch the
+// stream, and route output. Returns a typed error.
+func runChat(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, svc ChatService) error {
+	if opts.Query == "" {
+		return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty")
+	}
+	if opts.KBID == "" {
+		// Defensive: the cobra layer resolves KB before runChat; this guards
+		// the direct-test entry point.
+		return cmdutil.NewError(cmdutil.CodeKBIDRequired, "kb id is required")
+	}
+	if svc == nil {
+		return cmdutil.NewError(cmdutil.CodeServerError, "chat: no SDK client available")
+	}
+
+	// --format selects the output shape: json (default) accumulates and
+	// emits one object, ndjson streams raw SDK events, text renders live.
+	sessionID := opts.SessionID
+	autoCreated := false
+	if sessionID == "" {
+		sess, err := svc.CreateSession(ctx, &sdk.CreateSessionRequest{Title: "weknora chat"})
+		if err != nil {
+			// Ctrl-C during session creation: classify as cancelled so the
+			// hint nudges the user toward retry-with-signal-clean, not
+			// "pass --session" as session_create_failed would.
+			if cmdutil.IsCancelled(ctx, err) {
+				return cmdutil.Wrapf(cmdutil.CodeOperationCancelled, err, "chat cancelled")
+			}
+			// Map HTTP-shaped failures, but tag generic transport / unknown
+			// errors as session_create_failed so the dedicated hint fires.
+			code := cmdutil.ClassifyHTTPError(err)
+			if code == cmdutil.CodeNetworkError || code == cmdutil.CodeServerError {
+				code = cmdutil.CodeSessionCreateFailed
+			}
+			return cmdutil.Wrapf(code, err, "create chat session")
+		}
+		sessionID = sess.ID
+		autoCreated = true
+	}
+
+	if fopts != nil && fopts.Mode == cmdutil.FormatNDJSON {
+		return runChatNDJSON(ctx, opts, sessionID, svc)
+	}
+	if fopts != nil && fopts.Mode == cmdutil.FormatJSON {
+		return runChatJSON(ctx, opts, fopts, sessionID, svc)
+	}
+
+	// Surface the auto-created session ID up-front so a user who hits ^C
+	// mid-stream still has the pointer to resume - no need to scroll back
+	// past tokens. Skipped in json/ndjson mode (session_id is in the output).
+	if autoCreated {
+		fmt.Fprintf(iostreams.IO.Err, "session: %s (use --session to continue)\n", sessionID)
+	}
+
+	return runChatText(ctx, opts, sessionID, autoCreated, svc)
+}
+
+// runChatNDJSON handles the --format ndjson path: emits a CLI init event at
+// stream head, then passes every SDK event through verbatim as NDJSON lines.
+// No buffering — callers parse the stream incrementally.
+func runChatNDJSON(ctx context.Context, opts *Options, sessionID string, svc ChatService) error {
+	w := iostreams.IO.Out
+
+	// 1. Inject the CLI-managed init event at the head of the stream.
+	//    Carries the session pointer + retrieval context callers need for
+	//    follow-up threading.
+	initEv := output.InitEvent{
+		SessionID: sessionID,
+		KBID:      opts.KBID,
+		Profile:   cmdutil.GetProfile(),
+	}
+	if err := output.EmitInit(w, initEv); err != nil {
+		return err
+	}
+
+	// 2. Open SDK stream and pass each event through as a bare NDJSON line.
+	req := &sdk.KnowledgeQARequest{
+		Query:            opts.Query,
+		KnowledgeBaseIDs: []string{opts.KBID},
+		AgentEnabled:     false,
+		WebSearchEnabled: false,
+		Channel:          "api",
+	}
+	cb := func(r *sdk.StreamResponse) error {
+		// NDJSON is the raw protocol/debug surface: do not filter events or
+		// mutate their payloads. JSON/text modes own presentation filtering.
+		return output.EmitSDKEvent(w, r)
+	}
+	if err := svc.KnowledgeQAStream(ctx, sessionID, req, cb); err != nil {
+		if cmdutil.IsCancelled(ctx, err) {
+			return cmdutil.Wrapf(cmdutil.CodeOperationCancelled, err, "chat cancelled")
+		}
+		return cmdutil.WrapStream(err, "knowledge qa stream")
+	}
+	return nil
+}
+
+// runChatText handles the --format text path. It renders the same
+// projection as JSON immediately for both terminals and pipes.
+func runChatText(ctx context.Context, opts *Options, sessionID string, autoCreated bool, svc ChatService) error {
+	req := &sdk.KnowledgeQARequest{
+		Query:            opts.Query,
+		KnowledgeBaseIDs: []string{opts.KBID},
+		AgentEnabled:     false,
+		WebSearchEnabled: false,
+		Channel:          "api",
+	}
+
+	projector := sse.NewProjector(opts.Verbose, opts.Reference, opts.KBID)
+	renderer := sse.NewTextRenderer(iostreams.IO.Out, opts.Verbose)
+
+	cb := func(r *sdk.StreamResponse) error {
+		event, include := projector.Chat(r)
+		if !include {
+			return nil
+		}
+		return renderer.Write(event)
+	}
+
+	streamErr := svc.KnowledgeQAStream(ctx, sessionID, req, cb)
+	if streamErr != nil {
+		// Re-surface the auto-created session id on failure so a user who
+		// missed the start-of-stream notice (it scrolls past mid-stream
+		// tokens, especially on ^C) can still recover with --session.
+		if autoCreated {
+			fmt.Fprintf(iostreams.IO.Err, "session: %s (resume with --session %s)\n", sessionID, sessionID)
+		}
+		// Context cancelled (Ctrl-C) → user-aborted, exit 130 lineage.
+		if cmdutil.IsCancelled(ctx, streamErr) {
+			return cmdutil.Wrapf(cmdutil.CodeOperationCancelled, streamErr, "chat cancelled")
+		}
+		// Stream began (we observed at least one event) but never reached a
+		// terminal Done frame: typed as sse_stream_aborted so the hint
+		// nudges the user toward a retry.
+		if projector.Seen() && !projector.Done() {
+			return cmdutil.Wrapf(cmdutil.CodeSSEStreamAborted, streamErr, "stream aborted before completion")
+		}
+		// Pre-stream HTTP / transport failure: route through the canonical
+		// classifier so 401 / 404 / 5xx still surface their specific codes.
+		return cmdutil.WrapStream(streamErr, "knowledge qa stream")
+	}
+
+	// SDK returned nil but we never saw a Done event - server closed the
+	// connection cleanly mid-stream. Treat as aborted so the user sees the
+	// truncation rather than a silent partial answer. Includes the empty-body
+	// case (Done frame never arrived AND no content): better to surface the
+	// abort than emit ok=true with answer="" - agents can't distinguish the
+	// model genuinely had nothing to say from the stream getting cut.
+	if !projector.Done() {
+		return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")
+	}
+	return renderer.Close()
+}
+
+// runChatJSON handles the --format json path (the default): collect the
+// projection and emit it in one normal success envelope.
+func runChatJSON(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, sessionID string, svc ChatService) error {
+	req := &sdk.KnowledgeQARequest{
+		Query:            opts.Query,
+		KnowledgeBaseIDs: []string{opts.KBID},
+		AgentEnabled:     false,
+		WebSearchEnabled: false,
+		Channel:          "api",
+	}
+
+	projector := sse.NewProjector(opts.Verbose, opts.Reference, opts.KBID)
+	events := make([]sse.ProjectedEvent, 0)
+	cb := func(r *sdk.StreamResponse) error {
+		if event, include := projector.Chat(r); include {
+			events = append(events, event)
+		}
+		return nil
+	}
+
+	if err := svc.KnowledgeQAStream(ctx, sessionID, req, cb); err != nil {
+		if cmdutil.IsCancelled(ctx, err) {
+			return chatStreamError(cmdutil.Wrapf(cmdutil.CodeOperationCancelled, err, "chat cancelled"), sessionID, projector.AssistantMessageID())
+		}
+		return chatStreamError(cmdutil.WrapStream(err, "knowledge qa stream"), sessionID, projector.AssistantMessageID())
+	}
+	if !projector.Done() {
+		return chatStreamError(
+			cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event"),
+			sessionID,
+			projector.AssistantMessageID(),
+		)
+	}
+
+	sid := projector.SessionID()
+	if sid == "" {
+		sid = sessionID
+	}
+	data := chatResult{
+		Events:             events,
+		SessionID:          sid,
+		AssistantMessageID: projector.AssistantMessageID(),
+		KBID:               opts.KBID,
+		Query:              opts.Query,
+	}
+
+	// Reaching here means fopts.Mode is FormatJSON (the only caller). Route
+	// through FormatOptions.Emit so --jq projection and the success-envelope
+	// contract apply, matching every other non-streaming command. A nil fopts
+	// (direct-test entry) defaults to JSON so the object still emits.
+	if fopts == nil {
+		fopts = &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
+	}
+	return fopts.Emit(iostreams.IO.Out, data, nil)
+}
+
+func chatStreamError(err *cmdutil.Error, sessionID, assistantMessageID string) *cmdutil.Error {
+	detail := map[string]any{"session_id": sessionID}
+	if assistantMessageID != "" {
+		detail["assistant_message_id"] = assistantMessageID
+	}
+	return err.WithDetail(detail)
+}
+
+// chatResult is the --format json data payload. The projector controls default
+// versus verbose coverage.
+type chatResult struct {
+	Events             []sse.ProjectedEvent `json:"events"`
+	SessionID          string               `json:"session_id"`
+	AssistantMessageID string               `json:"assistant_message_id,omitempty"`
+	KBID               string               `json:"kb_id"`
+	Query              string               `json:"query"`
+}
+
+// compile-time check: the production SDK client implements ChatService.
+var _ ChatService = (*sdk.Client)(nil)
@@ -0,0 +1,656 @@
+package chat
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	"github.com/Tencent/WeKnora/cli/internal/sse"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// fakeChatService implements ChatService for unit tests. Tests configure the
+// callback driver via streamEvents (delivered in order) and observe captured
+// inputs through the exported fields.
+type fakeChatService struct {
+	createSessionResp *sdk.Session
+	createSessionErr  error
+	createCalled      bool
+
+	streamErr      error
+	streamEvents   []*sdk.StreamResponse
+	gotSessionID   string
+	gotRequest     *sdk.KnowledgeQARequest
+	streamCalled   bool
+	cbReturnsError error // if set, callback aborts after first event with this error
+}
+
+func (f *fakeChatService) CreateSession(_ context.Context, req *sdk.CreateSessionRequest) (*sdk.Session, error) {
+	f.createCalled = true
+	if f.createSessionErr != nil {
+		return nil, f.createSessionErr
+	}
+	if f.createSessionResp != nil {
+		return f.createSessionResp, nil
+	}
+	// Default: return a deterministic session id derived from the title so
+	// JSON assertions don't depend on uuid generation.
+	return &sdk.Session{ID: "sess_auto", Title: req.Title}, nil
+}
+
+func (f *fakeChatService) KnowledgeQAStream(ctx context.Context, sessionID string, req *sdk.KnowledgeQARequest, cb func(*sdk.StreamResponse) error, opts ...sdk.ResourceURLOptions) error {
+	f.streamCalled = true
+	f.gotSessionID = sessionID
+	f.gotRequest = req
+	for _, ev := range f.streamEvents {
+		if err := cb(ev); err != nil {
+			return err
+		}
+		if f.cbReturnsError != nil {
+			return f.cbReturnsError
+		}
+	}
+	return f.streamErr
+}
+
+// Sanity: fakeChatService must satisfy ChatService. Mirrors the production
+// var _ ChatService = (*sdk.Client)(nil) check at the bottom of chat.go.
+var _ ChatService = (*fakeChatService)(nil)
+
+// textOpts returns a FormatOptions configured for the text render path —
+// the most common shape under test.
+func textOpts() *cmdutil.FormatOptions {
+	return &cmdutil.FormatOptions{Mode: cmdutil.FormatText}
+}
+
+func TestChat_StreamMode(t *testing.T) {
+	out, errBuf := iostreams.SetForTestWithTTY(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "Hello "},
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "world"},
+			{ResponseType: sdk.ResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{
+				{KnowledgeID: "k1", KnowledgeTitle: "Doc One", Score: 0.42},
+			}},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true},
+		},
+	}
+	opts := &Options{Query: "hi", KBID: "kb_1"}
+	if err := runChat(context.Background(), opts, textOpts(), svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	got := out.String()
+	if !strings.Contains(got, "Hello world") {
+		t.Errorf("stdout missing streamed content: %q", got)
+	}
+	if strings.Contains(got, "references") || strings.Contains(got, "Doc One") {
+		t.Errorf("default text output leaked references: %q", got)
+	}
+	// auto-created session must announce itself on stderr
+	if !strings.Contains(errBuf.String(), "session: sess_auto") {
+		t.Errorf("expected stderr session hint, got %q", errBuf.String())
+	}
+	if !svc.createCalled {
+		t.Error("expected CreateSession invocation when SessionID empty")
+	}
+	if svc.gotSessionID != "sess_auto" {
+		t.Errorf("stream sessionID: got %q want sess_auto", svc.gotSessionID)
+	}
+	if svc.gotRequest == nil || svc.gotRequest.Channel != "api" {
+		t.Errorf("expected Channel=api, got %+v", svc.gotRequest)
+	}
+}
+
+// TestChat_NDJSON_FirstLineIsInit verifies that the NDJSON path (--format ndjson)
+// always injects an "init" line first carrying session_id and kb_id.
+func TestChat_NDJSON_FirstLineIsInit(t *testing.T) {
+	out, errBuf := iostreams.SetForTest(t)
+
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "answer"},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true},
+		},
+	}
+	opts := &Options{Query: "q", KBID: "kb_42"}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
+	if err := runChat(context.Background(), opts, fopts, svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+
+	// NDJSON mode must NOT print the session hint to stderr.
+	if errBuf.Len() != 0 {
+		t.Errorf("expected empty stderr in NDJSON mode, got %q", errBuf.String())
+	}
+
+	lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n")
+	if len(lines) == 0 {
+		t.Fatal("no output")
+	}
+	var first struct {
+		Type      string `json:"type"`
+		SessionID string `json:"session_id"`
+		KBID      string `json:"kb_id"`
+	}
+	if err := json.Unmarshal([]byte(lines[0]), &first); err != nil {
+		t.Fatalf("first line not JSON: %v\n  %s", err, lines[0])
+	}
+	if first.Type != "init" {
+		t.Errorf("first line type: got %q, want init", first.Type)
+	}
+	if first.SessionID != "sess_auto" {
+		t.Errorf("init.session_id: got %q, want sess_auto", first.SessionID)
+	}
+	if first.KBID != "kb_42" {
+		t.Errorf("init.kb_id: got %q, want kb_42", first.KBID)
+	}
+}
+
+// TestChat_NDJSON_PassthroughEvents verifies that the NDJSON path emits
+// init + N SDK events = N+1 total lines (no buffering, no extra wrapping).
+func TestChat_NDJSON_PassthroughEvents(t *testing.T) {
+	out, _ := iostreams.SetForTest(t)
+
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "hello"},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true},
+		},
+	}
+	opts := &Options{Query: "q", KBID: "kb_x"}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
+	if err := runChat(context.Background(), opts, fopts, svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+
+	lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n")
+	// 1 init + 2 SDK events = 3 lines.
+	if len(lines) != 3 {
+		t.Fatalf("got %d lines, want 3:\n%s", len(lines), out.String())
+	}
+	// Each must be valid JSON.
+	for i, line := range lines {
+		var obj map[string]any
+		if err := json.Unmarshal([]byte(line), &obj); err != nil {
+			t.Errorf("line %d not valid JSON: %v\n  %s", i+1, err, line)
+		}
+	}
+}
+
+func TestChat_NonTTY_StreamsSameProjection(t *testing.T) {
+	out, _ := iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "piped"},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true},
+		},
+	}
+	opts := &Options{Query: "q", KBID: "kb"}
+	if err := runChat(context.Background(), opts, textOpts(), svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	if !strings.Contains(out.String(), "piped") {
+		t.Errorf("expected accumulated answer, got %q", out.String())
+	}
+}
+
+func TestChat_NonTTY_VerboseIncludesThinking(t *testing.T) {
+	out, _ := iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeThinking, Content: "REASONING"},
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "answer"},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true},
+		},
+	}
+	opts := &Options{Query: "q", KBID: "kb", Verbose: true}
+	if err := runChat(context.Background(), opts, textOpts(), svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	if got := out.String(); !strings.Contains(got, "REASONING") || !strings.Contains(got, "answer") {
+		t.Errorf("non-TTY verbose output missing thinking or answer: %q", got)
+	}
+}
+
+func TestChat_SessionIDProvided(t *testing.T) {
+	_, errBuf := iostreams.SetForTestWithTTY(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{{ResponseType: sdk.ResponseTypeComplete, Done: true}},
+	}
+	opts := &Options{Query: "q", KBID: "kb", SessionID: "sess_existing"}
+	if err := runChat(context.Background(), opts, textOpts(), svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	if svc.createCalled {
+		t.Error("CreateSession must NOT be invoked when --session is provided")
+	}
+	if svc.gotSessionID != "sess_existing" {
+		t.Errorf("stream sessionID: got %q want sess_existing", svc.gotSessionID)
+	}
+	// No auto-create message because the user supplied the id.
+	if strings.Contains(errBuf.String(), "session:") {
+		t.Errorf("unexpected session hint emitted with explicit --session: %q", errBuf.String())
+	}
+}
+
+func TestChat_KBIDRequired(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeChatService{}
+	// Run with KBID empty (bypassing the cobra resolver).
+	opts := &Options{Query: "q"}
+	err := runChat(context.Background(), opts, textOpts(), svc)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %T", err)
+	}
+	if typed.Code != cmdutil.CodeKBIDRequired {
+		t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeKBIDRequired)
+	}
+	if svc.createCalled || svc.streamCalled {
+		t.Error("KB validation must short-circuit before any SDK call")
+	}
+}
+
+func TestChat_EmptyQuery(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeChatService{}
+	opts := &Options{Query: "", KBID: "kb"}
+	err := runChat(context.Background(), opts, textOpts(), svc)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %T", err)
+	}
+	if typed.Code != cmdutil.CodeInputInvalidArgument {
+		t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeInputInvalidArgument)
+	}
+}
+
+func TestChat_SDKError_PreStream(t *testing.T) {
+	// SDK fails before any event arrives → ClassifyHTTPError mapping.
+	// "HTTP error 401: ..." → auth.unauthenticated.
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		streamErr: errors.New("HTTP error 401: token rejected"),
+	}
+	opts := &Options{Query: "q", KBID: "kb"}
+	err := runChat(context.Background(), opts, textOpts(), svc)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %T", err)
+	}
+	if typed.Code != cmdutil.CodeAuthUnauthenticated {
+		t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeAuthUnauthenticated)
+	}
+}
+
+func TestChat_SDKError_MidStream_AbortsAsSSE(t *testing.T) {
+	// Some content arrived, then the stream errored without a Done event →
+	// CodeSSEStreamAborted (separate from generic transport failure).
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{{Content: "partial"}},
+		streamErr:    errors.New("connection reset"),
+	}
+	opts := &Options{Query: "q", KBID: "kb"}
+	err := runChat(context.Background(), opts, textOpts(), svc)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %T", err)
+	}
+	if typed.Code != cmdutil.CodeSSEStreamAborted {
+		t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeSSEStreamAborted)
+	}
+}
+
+func TestChat_TerminalSSEError_ClassifiesAsServerError(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "partial"},
+			{ResponseType: sdk.ResponseTypeError, Content: "boom", Done: true},
+		},
+		streamErr: sdk.NewSSEStreamError("boom"),
+	}
+	opts := &Options{Query: "q", KBID: "kb"}
+	err := runChat(context.Background(), opts, textOpts(), svc)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %T", err)
+	}
+	if typed.Code != cmdutil.CodeServerError {
+		t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeServerError)
+	}
+}
+
+func TestChat_ContextCancelled(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // simulate Ctrl-C delivered before the SDK returns.
+	svc := &fakeChatService{streamErr: context.Canceled}
+	opts := &Options{Query: "q", KBID: "kb"}
+	err := runChat(ctx, opts, textOpts(), svc)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %T", err)
+	}
+	if typed.Code != cmdutil.CodeOperationCancelled {
+		t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeOperationCancelled)
+	}
+}
+
+func TestChat_SessionCreateFails(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		createSessionErr: errors.New("dial tcp: connection refused"),
+	}
+	opts := &Options{Query: "q", KBID: "kb"}
+	err := runChat(context.Background(), opts, textOpts(), svc)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %T", err)
+	}
+	if typed.Code != cmdutil.CodeSessionCreateFailed {
+		t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeSessionCreateFailed)
+	}
+	if svc.streamCalled {
+		t.Error("stream must not be invoked after session creation failed")
+	}
+}
+
+func TestChat_SessionCreate404SurfacesNotFound(t *testing.T) {
+	// HTTP-shaped session-create failures should NOT collapse into the
+	// session_create_failed bucket; they keep their canonical mapping so
+	// agents can react to e.g. resource.not_found.
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		createSessionErr: errors.New("HTTP error 404: tenant not found"),
+	}
+	opts := &Options{Query: "q", KBID: "kb"}
+	err := runChat(context.Background(), opts, textOpts(), svc)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %T", err)
+	}
+	if typed.Code != cmdutil.CodeResourceNotFound {
+		t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeResourceNotFound)
+	}
+}
+
+// TestChat_NDJSON_InitIncludesProfile verifies that when a profile is set,
+// the NDJSON init event carries the profile field.
+func TestChat_NDJSON_InitIncludesProfile(t *testing.T) {
+	cmdutil.SetProfile("prod")
+	t.Cleanup(func() { cmdutil.SetProfile("") })
+
+	out, _ := iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeComplete, Done: true},
+		},
+	}
+	opts := &Options{Query: "q", KBID: "kb_x"}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
+	if err := runChat(context.Background(), opts, fopts, svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+
+	lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n")
+	if len(lines) == 0 {
+		t.Fatal("no output")
+	}
+	var initLine struct {
+		Type    string `json:"type"`
+		Profile string `json:"profile"`
+	}
+	if err := json.Unmarshal([]byte(lines[0]), &initLine); err != nil {
+		t.Fatalf("first line not JSON: %v\n  %s", err, lines[0])
+	}
+	if initLine.Type != "init" {
+		t.Errorf("type: got %q, want init", initLine.Type)
+	}
+	if initLine.Profile != "prod" {
+		t.Errorf("profile: got %q, want prod", initLine.Profile)
+	}
+}
+
+func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) {
+	// NDJSON is the raw protocol surface: every SDK event passes through,
+	// including reasoning, regardless of the presentation-oriented --verbose.
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeThinking, Content: "search KB"},
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "hello"},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_x"},
+		},
+	}
+	out, _ := iostreams.SetForTest(t)
+
+	opts := &Options{Query: "hi", KBID: "kb_x"}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
+	if err := runChat(context.Background(), opts, fopts, svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n")
+	// 1 init + thinking + answer + complete = 4 lines.
+	if len(lines) != 4 {
+		t.Fatalf("got %d lines, want 4:\n%s", len(lines), out.String())
+	}
+	sawThinking := false
+	for i, line := range lines {
+		var ev map[string]any
+		if err := json.Unmarshal([]byte(line), &ev); err != nil {
+			t.Fatalf("line %d not JSON: %v", i+1, err)
+		}
+		if ev["response_type"] == "thinking" {
+			sawThinking = true
+		}
+	}
+	if !sawThinking {
+		t.Error("thinking event was filtered from raw NDJSON output")
+	}
+	// First line: CLI-injected init event.
+	var initLine map[string]any
+	if err := json.Unmarshal([]byte(lines[0]), &initLine); err != nil {
+		t.Fatalf("line 1 (init) not JSON: %v", err)
+	}
+	if initLine["type"] != "init" {
+		t.Errorf("first line type=%v, want init", initLine["type"])
+	}
+}
+
+func TestChat_FormatNDJSON_VerboseDoesNotAlterRawStream(t *testing.T) {
+	// --verbose is presentation-only; NDJSON remains the same raw stream and
+	// therefore still contains thinking alongside answer + complete.
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeThinking, Content: "search KB"},
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "hello"},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_x"},
+		},
+	}
+	out, _ := iostreams.SetForTest(t)
+
+	opts := &Options{Query: "hi", KBID: "kb_x", Verbose: true}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
+	if err := runChat(context.Background(), opts, fopts, svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n")
+	// 1 init + thinking + answer + complete = 4 lines.
+	if len(lines) != 4 {
+		t.Fatalf("got %d lines, want 4:\n%s", len(lines), out.String())
+	}
+	var second map[string]any
+	if err := json.Unmarshal([]byte(lines[1]), &second); err != nil {
+		t.Fatalf("line 2 not JSON: %v", err)
+	}
+	if second["response_type"] != "thinking" {
+		t.Errorf("second event response_type=%v, want thinking", second["response_type"])
+	}
+}
+
+func TestChat_FormatJSON_ReferenceAddsIndexes(t *testing.T) {
+	out, _ := iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "the answer"},
+			{ResponseType: sdk.ResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{
+				{ID: "c1", Content: "BULKY FULL CHUNK CONTENT", ParentChunkID: "p1", KnowledgeTitle: "Doc One", Score: 0.5},
+			}},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_auto"},
+		},
+	}
+	opts := &Options{Query: "hi", KBID: "kb_1", Reference: true}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
+	if err := runChat(context.Background(), opts, fopts, svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	// A single envelope, not multiple NDJSON lines.
+	outStr := strings.TrimRight(out.String(), "\n")
+	if strings.Contains(outStr, "\n") {
+		t.Fatalf("expected single-line envelope, got multiple lines:\n%s", outStr)
+	}
+	var env struct {
+		OK   bool `json:"ok"`
+		Data struct {
+			Events    []sse.ProjectedEvent `json:"events"`
+			SessionID string               `json:"session_id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(outStr), &env); err != nil {
+		t.Fatalf("envelope not JSON: %v\n%s", err, outStr)
+	}
+	if !env.OK {
+		t.Error("ok=false, want true")
+	}
+	wantTypes := []string{"answer", "references"}
+	if len(env.Data.Events) != len(wantTypes) {
+		t.Fatalf("events=%+v", env.Data.Events)
+	}
+	for i, want := range wantTypes {
+		if env.Data.Events[i].ResponseType != want {
+			t.Errorf("events[%d].response_type=%q, want %q", i, env.Data.Events[i].ResponseType, want)
+		}
+	}
+	refs := env.Data.Events[1].KnowledgeReferences
+	if len(refs) != 1 || refs[0].KBID != "kb_1" || refs[0].ChunkID != "c1" || refs[0].ParentChunkID != "p1" {
+		t.Errorf("reference indexes=%+v", refs)
+	}
+	if env.Data.SessionID == "" {
+		t.Error("session_id empty")
+	}
+}
+
+func TestChat_FormatNDJSON_PreservesReflection(t *testing.T) {
+	// Reflection is part of the raw SDK protocol and must not be filtered.
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeReflection, Content: "reflecting"},
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "hello"},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_x"},
+		},
+	}
+	out, _ := iostreams.SetForTest(t)
+
+	opts := &Options{Query: "hi", KBID: "kb_x"}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
+	if err := runChat(context.Background(), opts, fopts, svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	sawReflection := false
+	for i, line := range strings.Split(strings.TrimRight(out.String(), "\n"), "\n") {
+		var ev map[string]any
+		if err := json.Unmarshal([]byte(line), &ev); err != nil {
+			t.Fatalf("line %d not JSON: %v", i+1, err)
+		}
+		if ev["response_type"] == "reflection" {
+			sawReflection = true
+		}
+	}
+	if !sawReflection {
+		t.Error("reflection event was filtered from raw NDJSON output")
+	}
+}
+
+func TestChat_FormatJSON_HonorsJQ(t *testing.T) {
+	// --format json routes through FormatOptions.Emit, so --jq projects the
+	// envelope instead of dumping it whole. Guards the agent output protocol
+	// contract: consumers can join answer event fragments.
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{
+			{ResponseType: sdk.ResponseTypeAnswer, Content: "the answer"},
+			{ResponseType: sdk.ResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{
+				{ID: "c1", Content: "bulk", KnowledgeTitle: "Doc"},
+			}},
+			{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_x"},
+		},
+	}
+	out, _ := iostreams.SetForTest(t)
+
+	opts := &Options{Query: "hi", KBID: "kb_1"}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON, JQ: `[.data.events[].content] | join("")`}
+	if err := runChat(context.Background(), opts, fopts, svc); err != nil {
+		t.Fatalf("runChat: %v", err)
+	}
+	got := strings.TrimSpace(out.String())
+	if !strings.Contains(got, "the answer") {
+		t.Errorf("jq output missing projected answer: %q", got)
+	}
+	// A projection must not dump the full envelope scaffolding.
+	if strings.Contains(got, "references") || strings.Contains(got, "session_id") {
+		t.Errorf("jq output looks like a full envelope, not a projection: %q", got)
+	}
+}
+
+func TestChat_FormatJSON_StreamErrorIncludesSessionDetail(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeChatService{
+		streamEvents: []*sdk.StreamResponse{{
+			ResponseType:       sdk.ResponseTypeAgentQuery,
+			AssistantMessageID: "msg_123",
+		}},
+		streamErr: errors.New("connection reset"),
+	}
+	err := runChat(
+		context.Background(),
+		&Options{Query: "q", KBID: "kb"},
+		&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON},
+		svc,
+	)
+	var typed *cmdutil.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("expected *cmdutil.Error, got %v", err)
+	}
+	detail, ok := typed.Detail.(map[string]any)
+	if !ok || detail["session_id"] != "sess_auto" || detail["assistant_message_id"] != "msg_123" {
+		t.Errorf("error detail=%v, want session and assistant message ids", typed.Detail)
+	}
+}