diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 5925a8fd..e14c0631 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -77,11 +77,15 @@ token (emitting as a JSON array is planned for v0.8). `detail` carries structured per-error context (e.g. `unknown_subcommand`'s `available[]` list). -### NDJSON event stream (chat / session ask) +### Buffered JSON and NDJSON streams (chat / session ask) -`--format json` and `--format ndjson` both produce one JSON event per line — -no envelope wrapping. The CLI injects exactly one event (`init`) at the head; -all subsequent events pass through verbatim from the SDK: +`--format json` (the default) buffers the SSE stream and emits one normal +success envelope whose `data.events` contains answer events by default. +`--reference` adds `kb_id` / `chunk_id` / `parent_chunk_id` indexes; +`--verbose` adds reasoning, tool, metadata, and lifecycle events. `--format +text` renders the same projection live. +`--format ndjson` is the raw event/debug surface: the CLI injects exactly one +`init` event at the head and passes all subsequent SDK events through verbatim: ``` {"type":"init","session_id":"...","kb_id":"...","profile":"...","agent_id":"..."} @@ -91,7 +95,9 @@ all subsequent events pass through verbatim from the SDK: {"type":"complete","done":true} ``` -For prose rendering, pass `--format text`. +MCP `chat` / `session_ask` return the same `events` shape and accept +`reference` / `verbose` booleans. NDJSON ignores both presentation flags and +always stays raw. ### `_notice` evolution policy @@ -170,8 +176,8 @@ is or isn't aligned with. | | | |---|---| -| **WeKnora** | streaming commands (`chat`, `session ask`) emit bare `{type:...}` per line; no envelope | -| **Rationale** | This matches established practice across NDJSON-emitting CLIs and webhook protocols. A streaming envelope requires unwrap before dispatch — net burden with no benefit. | +| **WeKnora** | `chat` / `session ask --format ndjson` emit bare `{type:...}` per line; default JSON buffers a bounded answer-event projection into one envelope | +| **Rationale** | This matches established practice across NDJSON-emitting CLIs and webhook protocols. Each complete line can be decoded and dispatched as it arrives; the buffered envelope is reserved for normal JSON mode. | ### 5. No `schema_version` field in payload diff --git a/cli/CHANGELOG.md b/cli/CHANGELOG.md index 280a9287..a47ab017 100644 --- a/cli/CHANGELOG.md +++ b/cli/CHANGELOG.md @@ -12,6 +12,29 @@ CLI history before v0.3 is recorded in the project root ## [Unreleased] +### Breaking +- `chat` and `session ask` now distinguish JSON from NDJSON: the default + `--format json` buffers a bounded answer-event projection into one + `{ok:true,data:{events:[...]}}` envelope; use `--format ndjson` for the + complete raw event stream. +- JSON, text, and MCP chat/session output hide reasoning, tools, lifecycle + frames, and references by default. `--reference` adds bounded `kb_id` / + `chunk_id` / `parent_chunk_id` indexes; `--verbose` adds execution events. + +### Added +- `chat` / `session ask --reference` includes indexed citations, while + `--verbose` includes reasoning, tools, and lifecycle events. MCP `chat` / + `session_ask` expose the same controls through `reference` / `verbose` inputs. +- Buffered chat/session errors include the auto-created `session_id` in + `error.detail` so interrupted sessions remain recoverable. + +### Changed +- JSON, text, and MCP now share one event projector and filtering policy. +- Projected references contain lookup indexes only; fetch full + passages with `chunk view ` or `chunk view `. +- NDJSON remains an unmodified SDK event trace, including reasoning and full + reference payloads. + ### Fixed - Streaming SDK calls are no longer cut off by the client's default 30-second timeout (explicit `WithTimeout` values remain honored), and SSE data lines @@ -20,7 +43,8 @@ CLI history before v0.3 is recorded in the project root even when the server leaves the HTTP connection open. - Agent accumulation now waits for `response_type=complete` instead of treating per-event `done:true` markers as completion of the whole run. -- Reference `parent_chunk_id` / `sub_chunk_id` fields now survive SDK unmarshal. +- Reference `knowledge_base_id`, `parent_chunk_id`, and `sub_chunk_id` fields + now survive SDK unmarshal. ## [0.9.0] - 2026-06-10 diff --git a/cli/README.md b/cli/README.md index 213ae83f..136ea65b 100644 --- a/cli/README.md +++ b/cli/README.md @@ -252,8 +252,10 @@ is the guard against unintended writes. ### Other AI-agent ergonomics -- For chat / session ask in AI-agent contexts, pass `--format json` — - streaming tokens to stdout makes JSON parsing impossible. +- For chat / session ask in AI-agent contexts, pass `--format json` for a + bounded answer-event envelope. Add `--reference` for indexed citations, + `--verbose` for reasoning/tools/lifecycle events, or `--format ndjson` for + the unmodified raw stream. - `--format json` composes with the global `--profile ` for single-shot profile overrides without disk writes. - `weknora mcp serve` exposes a curated read-only tool surface over diff --git a/cli/cmd/chat/chat.go b/cli/cmd/chat/chat.go index c18e9d83..b9078081 100644 --- a/cli/cmd/chat/chat.go +++ b/cli/cmd/chat/chat.go @@ -1,21 +1,22 @@ // Package chat implements `weknora chat ` - the streaming RAG answer // entry point. // -// Two output modes share a single SDK call: +// Three output modes share a single SDK call: // -// - Stream mode (TTY + --format text): write each StreamResponse.Content -// fragment directly to iostreams.IO.Out as it arrives, then print a -// footer with knowledge references. This is the "feels alive" UX a -// human typing in a terminal expects. +// - 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. // -// - NDJSON mode (--format json / --format ndjson / pipe): inject a CLI -// "init" event at stream head, then pass through every SDK event verbatim -// as NDJSON lines. Agents and pipes get a live event stream they can -// parse incrementally. --format json routes here too — buffered JSON -// envelope makes no sense for a streaming command. +// - 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 neither mode needs locking. The runChat core takes a +// 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 @@ -28,26 +29,31 @@ import ( "github.com/spf13/cobra" "github.com/Tencent/WeKnora/cli/internal/cmdutil" - "github.com/Tencent/WeKnora/cli/internal/format" "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 NDJSON init-event fields surfaced for -// `--format json` / `--format ndjson` discovery on `chat`. Reflects the -// InitEvent head line + the raw SDK event vocabulary. +// 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{ - "session_id", "kb_id", - // SDK event fields (pass-through): response_type, content, done, - // knowledge_references, assistant_message_id, session_id + "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 @@ -69,12 +75,14 @@ answer back. By default a fresh session is created on first invocation; pass --session to continue an existing conversation. Modes: - --format text: live token streaming + reference footer - --format json / --format ndjson / pipe (default): NDJSON event stream — - one init line at head (session_id, kb_id), - then raw SDK events verbatim. Both json - and ndjson flags produce the same NDJSON - stream.`, + --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`, @@ -103,12 +111,17 @@ Modes: } 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 streaming RAG question against a knowledge base. Produces an NDJSON event stream: init line (session_id, kb_id) then raw SDK events. Use --format json or --format ndjson.", + 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{"--kb"}, - Examples: []string{`weknora chat "What is RRF?" --kb kb_abc --format json`}, - Output: "NDJSON stream: {type:init, session_id, kb_id} then SDK events (response_type, content, done, knowledge_references, ...)", + 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 } @@ -128,11 +141,8 @@ func runChat(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, s return cmdutil.NewError(cmdutil.CodeServerError, "chat: no SDK client available") } - // Streaming commands route --format json AND --format ndjson to the - // NDJSON event-stream path. A buffered envelope makes no sense for a - // streaming command. Only --format text uses the live renderer. - ndjsonMode := fopts != nil && (fopts.Mode == cmdutil.FormatJSON || fopts.Mode == cmdutil.FormatNDJSON) - + // --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 == "" { @@ -156,13 +166,16 @@ func runChat(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, s autoCreated = true } - if ndjsonMode { + 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 NDJSON mode (it appears in the init event). + // 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) } @@ -170,10 +183,9 @@ func runChat(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, s return runChatText(ctx, opts, sessionID, autoCreated, svc) } -// runChatNDJSON handles --format json and --format ndjson paths. -// 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. +// 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 @@ -198,6 +210,8 @@ func runChatNDJSON(ctx context.Context, opts *Options, sessionID string, svc Cha 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 { @@ -209,12 +223,9 @@ func runChatNDJSON(ctx context.Context, opts *Options, sessionID string, svc Cha return nil } -// runChatText handles the --format text path. Streams content fragments -// live on TTY; accumulates then renders on non-TTY pipes. +// 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 { - // Stream mode requires an interactive stdout. - streamMode := iostreams.IO.IsStdoutTTY() - req := &sdk.KnowledgeQARequest{ Query: opts.Query, KnowledgeBaseIDs: []string{opts.KBID}, @@ -223,16 +234,15 @@ func runChatText(ctx context.Context, opts *Options, sessionID string, autoCreat Channel: "api", } - acc := &sse.Accumulator{} + projector := sse.NewProjector(opts.Verbose, opts.Reference, opts.KBID) + renderer := sse.NewTextRenderer(iostreams.IO.Out, opts.Verbose) cb := func(r *sdk.StreamResponse) error { - if streamMode && r != nil && r.Content != "" { - // Best-effort write; if stdout dies the SDK will surface the - // error on the next iteration. No need to bail early. - _, _ = iostreams.IO.Out.Write([]byte(r.Content)) + event, include := projector.Chat(r) + if !include { + return nil } - acc.Append(r) - return nil + return renderer.Write(event) } streamErr := svc.KnowledgeQAStream(ctx, sessionID, req, cb) @@ -250,7 +260,7 @@ func runChatText(ctx context.Context, opts *Options, sessionID string, autoCreat // 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 acc.Result() != "" && !acc.Done() { + if projector.Seen() && !projector.Done() { return cmdutil.Wrapf(cmdutil.CodeSSEStreamAborted, streamErr, "stream aborted before completion") } // Pre-stream HTTP / transport failure: route through the canonical @@ -264,30 +274,84 @@ func runChatText(ctx context.Context, opts *Options, sessionID string, autoCreat // 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 !acc.Done() { + if !projector.Done() { return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event") } + return renderer.Close() +} - answer := acc.Result() - references := acc.References - - // Streaming mode already wrote the answer body via the callback, so we - // only need to render the trailing references (and a closing newline). - // Non-TTY accumulate path writes the answer here for the first time. - out := iostreams.IO.Out - if streamMode { - // Ensure the answer line ends cleanly before the references footer. - if !strings.HasSuffix(answer, "\n") { - fmt.Fprintln(out) - } - } else { - fmt.Fprint(out, answer) - if !strings.HasSuffix(answer, "\n") { - fmt.Fprintln(out) - } +// 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", } - format.WriteReferences(out, references) - return nil + + 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.WrapHTTP(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. diff --git a/cli/cmd/chat/chat_test.go b/cli/cmd/chat/chat_test.go index d86addcc..b5495c3c 100644 --- a/cli/cmd/chat/chat_test.go +++ b/cli/cmd/chat/chat_test.go @@ -9,6 +9,7 @@ import ( "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" ) @@ -86,11 +87,8 @@ func TestChat_StreamMode(t *testing.T) { if !strings.Contains(got, "Hello world") { t.Errorf("stdout missing streamed content: %q", got) } - if !strings.Contains(got, "References") { - t.Errorf("stdout missing references footer: %q", got) - } - if !strings.Contains(got, "Doc One") { - t.Errorf("references should render KnowledgeTitle, got %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") { @@ -107,7 +105,7 @@ func TestChat_StreamMode(t *testing.T) { } } -// TestChat_NDJSON_FirstLineIsInit verifies that the NDJSON path (--format json) +// 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) @@ -119,7 +117,7 @@ func TestChat_NDJSON_FirstLineIsInit(t *testing.T) { }, } opts := &Options{Query: "q", KBID: "kb_42"} - fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON} + fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON} if err := runChat(context.Background(), opts, fopts, svc); err != nil { t.Fatalf("runChat: %v", err) } @@ -164,7 +162,7 @@ func TestChat_NDJSON_PassthroughEvents(t *testing.T) { }, } opts := &Options{Query: "q", KBID: "kb_x"} - fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON} + fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON} if err := runChat(context.Background(), opts, fopts, svc); err != nil { t.Fatalf("runChat: %v", err) } @@ -183,34 +181,7 @@ func TestChat_NDJSON_PassthroughEvents(t *testing.T) { } } -// TestChat_NDJSON_JSONEqualsNDJSON verifies that --format json and --format ndjson -// produce identical byte output on a streaming command. -func TestChat_NDJSON_JSONEqualsNDJSON(t *testing.T) { - events := []*sdk.StreamResponse{ - {ResponseType: sdk.ResponseTypeAnswer, Content: "hello"}, - {ResponseType: sdk.ResponseTypeComplete, Done: true}, - } - - runWith := func(mode cmdutil.FormatMode) string { - out, _ := iostreams.SetForTest(t) - svc := &fakeChatService{streamEvents: events} - opts := &Options{Query: "q", KBID: "kb_x"} - fopts := &cmdutil.FormatOptions{Mode: mode} - if err := runChat(context.Background(), opts, fopts, svc); err != nil { - t.Fatalf("runChat(%s): %v", mode, err) - } - return out.String() - } - - jsonOut := runWith(cmdutil.FormatJSON) - ndjsonOut := runWith(cmdutil.FormatNDJSON) - if jsonOut != ndjsonOut { - t.Errorf("--format json and --format ndjson differ:\n json: %q\n ndjson: %q", jsonOut, ndjsonOut) - } -} - -func TestChat_NonTTY_AccumulateMode(t *testing.T) { - // Non-TTY iostreams forces accumulate mode. +func TestChat_NonTTY_StreamsSameProjection(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &fakeChatService{ streamEvents: []*sdk.StreamResponse{ @@ -227,6 +198,24 @@ func TestChat_NonTTY_AccumulateMode(t *testing.T) { } } +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{ @@ -430,8 +419,8 @@ func TestChat_NDJSON_InitIncludesProfile(t *testing.T) { } func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) { - // Fake stream emits 3 events: thinking, answer, complete. - // With the init injection, total output is 4 lines (1 init + 3 SDK events). + // 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"}, @@ -447,11 +436,23 @@ func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) { t.Fatalf("runChat: %v", err) } lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n") - // 1 init + 3 SDK events = 4 lines. + // 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 { @@ -460,8 +461,30 @@ func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) { if initLine["type"] != "init" { t.Errorf("first line type=%v, want init", initLine["type"]) } +} - // Second line: thinking event (SDK passthrough). +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) @@ -469,20 +492,142 @@ func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) { if second["response_type"] != "thinking" { t.Errorf("second event response_type=%v, want thinking", second["response_type"]) } - // Third line: answer. - var third map[string]any - if err := json.Unmarshal([]byte(lines[2]), &third); err != nil { - t.Fatalf("line 3 not JSON: %v", err) +} + +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"}, + }, } - if third["response_type"] != "answer" { - t.Errorf("third event response_type=%v, want answer", third["response_type"]) + 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) } - // Fourth line: complete with done=true. - var fourth map[string]any - if err := json.Unmarshal([]byte(lines[3]), &fourth); err != nil { - t.Fatalf("line 4 not JSON: %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) } - if fourth["done"] != true { - t.Errorf("fourth event done=%v, want true", fourth["done"]) + 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) } } diff --git a/cli/cmd/session/ask.go b/cli/cmd/session/ask.go index 7696f886..0b6f3d48 100644 --- a/cli/cmd/session/ask.go +++ b/cli/cmd/session/ask.go @@ -3,26 +3,24 @@ package sessioncmd import ( "context" "fmt" - "io" "strings" "github.com/spf13/cobra" "github.com/Tencent/WeKnora/cli/internal/cmdutil" - "github.com/Tencent/WeKnora/cli/internal/format" "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" ) -// sessionAskFields enumerates the NDJSON init-event fields surfaced for -// `--format json` / `--format ndjson` discovery on `session ask`. Reflects -// the InitEvent head line + the raw SDK agent event vocabulary. +// sessionAskFields enumerates the fields surfaced for `--jq` projection +// discovery on `session ask`: the json object's data fields + the raw SDK +// agent event vocabulary used by --format ndjson. var sessionAskFields = []string{ - "session_id", "agent_id", - // SDK event fields (pass-through): response_type, content, done, - // knowledge_references, tool_call_id, tool_result + "events", "session_id", "agent_id", "query", + // NDJSON init + SDK event fields. + "type", "profile", "response_type", "content", "done", "knowledge_references", "data", } // AskOptions captures `session ask` flag state. @@ -30,6 +28,12 @@ type AskOptions struct { AgentID string Query string SessionID string // --session: continue an existing session (skip auto-create) + // 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 } // AskService is the narrow SDK surface this command depends on. @@ -60,12 +64,14 @@ The 'weknora agent' subtree handles CRUD only (list / view / create / edit / delete / status / check). Modes: - --format text: live answer streaming + tool-trace footer - --format json / --format ndjson / pipe (default): NDJSON event stream — - one init line at head (session_id, agent_id), - then raw SDK agent events verbatim. Both - json and ndjson flags produce the same - NDJSON stream.`, + --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, + agent_id) then SDK agent events verbatim. Debug. + +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 session ask --agent ag_x "Summarize Q3 sales" weknora session ask --session sess_x --agent ag_x "Follow-up question" weknora session ask --agent ag_x "Multi-step task" --format ndjson`, @@ -87,15 +93,18 @@ Modes: cmd.Flags().StringVarP(&opts.AgentID, "agent", "a", "", "Agent ID to invoke (required)") _ = cmd.MarkFlagRequired("agent") 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, sessionAskFields...) cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ - UsedFor: "Invoke a custom agent in a session context. Produces an NDJSON event stream: init line (session_id, agent_id) then raw SDK agent events. Use --format json or --format ndjson.", + UsedFor: "Invoke a custom agent in a session context. Default JSON returns a bounded answer-event projection. --reference adds indexed citations; --verbose adds reasoning, tools, and lifecycle events. --format ndjson streams raw SDK agent events; --format text renders the selected events live.", RequiredFlags: []string{"--agent"}, Examples: []string{ - `weknora session ask --agent ag_x "Summarize Q3 sales" --format json`, - `weknora session ask --session sess_x --agent ag_x "Follow-up question" --format json`, + `weknora session ask --agent ag_x "Summarize Q3 sales"`, + `weknora session ask --agent ag_x "Summarize Q3 sales" --jq '[.data.events[].content] | join("")'`, + `weknora session ask --session sess_x --agent ag_x "Follow-up question"`, }, - Output: "NDJSON stream: {type:init, session_id, agent_id} then SDK agent events (response_type, content, done, knowledge_references, ...)", + Output: "Default --format json: {ok,data:{events:[answer...],session_id,agent_id,query}}. --reference adds kb_id/chunk_id reference events; --verbose adds execution events. --format ndjson remains raw.", }) return cmd } @@ -111,11 +120,8 @@ func runAsk(ctx context.Context, opts *AskOptions, fopts *cmdutil.FormatOptions, return cmdutil.NewError(cmdutil.CodeServerError, "session ask: no SDK client available") } - // Streaming commands route --format json AND --format ndjson to the - // NDJSON event-stream path. A buffered envelope makes no sense for a - // streaming command. Only --format text uses the live renderer. - ndjsonMode := fopts != nil && (fopts.Mode == cmdutil.FormatJSON || fopts.Mode == cmdutil.FormatNDJSON) - + // --format selects the output shape: json (default) accumulates and + // emits one object, ndjson streams raw SDK agent events, text renders. sessionID := opts.SessionID autoCreated := false if sessionID == "" { @@ -134,13 +140,16 @@ func runAsk(ctx context.Context, opts *AskOptions, fopts *cmdutil.FormatOptions, autoCreated = true } - if ndjsonMode { + if fopts != nil && fopts.Mode == cmdutil.FormatNDJSON { return runAskNDJSON(ctx, opts, sessionID, svc) } + if fopts != nil && fopts.Mode == cmdutil.FormatJSON { + return runAskJSON(ctx, opts, fopts, sessionID, svc) + } // Surface auto-created session id up-front so a ^C mid-stream still - // leaves a recoverable pointer. Skipped in NDJSON mode (it appears in - // the init event). + // leaves a recoverable pointer. 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) } @@ -148,9 +157,9 @@ func runAsk(ctx context.Context, opts *AskOptions, fopts *cmdutil.FormatOptions, return runAskText(ctx, opts, sessionID, autoCreated, svc) } -// runAskNDJSON handles --format json and --format ndjson paths. -// Emits a CLI init event at stream head, then passes every SDK agent event -// through verbatim as NDJSON lines. No buffering. +// runAskNDJSON handles the --format ndjson path: emits a CLI init event at +// stream head, then passes every SDK agent event through verbatim as NDJSON +// lines. No buffering. func runAskNDJSON(ctx context.Context, opts *AskOptions, sessionID string, svc AskService) error { w := iostreams.IO.Out @@ -173,6 +182,8 @@ func runAskNDJSON(ctx context.Context, opts *AskOptions, sessionID string, svc A Channel: "api", } cb := func(r *sdk.AgentStreamResponse) 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.AgentQAStreamWithRequest(ctx, sessionID, req, cb); err != nil { @@ -184,12 +195,9 @@ func runAskNDJSON(ctx context.Context, opts *AskOptions, sessionID string, svc A return nil } -// runAskText handles the --format text path. Streams answer fragments -// live on TTY; accumulates then renders on non-TTY pipes. +// runAskText handles the --format text path. It renders the same +// projection as JSON immediately for both terminals and pipes. func runAskText(ctx context.Context, opts *AskOptions, sessionID string, autoCreated bool, svc AskService) error { - // Stream mode requires an interactive stdout. - streamMode := iostreams.IO.IsStdoutTTY() - req := &sdk.AgentQARequest{ Query: opts.Query, AgentEnabled: true, @@ -197,13 +205,14 @@ func runAskText(ctx context.Context, opts *AskOptions, sessionID string, autoCre Channel: "api", } - acc := &sse.AgentAccumulator{} + projector := sse.NewProjector(opts.Verbose, opts.Reference, "") + renderer := sse.NewTextRenderer(iostreams.IO.Out, opts.Verbose) cb := func(r *sdk.AgentStreamResponse) error { - if streamMode && r != nil && r.ResponseType == sdk.AgentResponseTypeAnswer && r.Content != "" { - _, _ = iostreams.IO.Out.Write([]byte(r.Content)) + event, include := projector.Agent(r) + if !include { + return nil } - acc.Append(r) - return nil + return renderer.Write(event) } streamErr := svc.AgentQAStreamWithRequest(ctx, sessionID, req, cb) @@ -214,61 +223,79 @@ func runAskText(ctx context.Context, opts *AskOptions, sessionID string, autoCre if cmdutil.IsCancelled(ctx, streamErr) { return cmdutil.Wrapf(cmdutil.CodeOperationCancelled, streamErr, "session ask cancelled") } - if acc.Answer() != "" && !acc.Done() { + if projector.Seen() && !projector.Done() { return cmdutil.Wrapf(cmdutil.CodeSSEStreamAborted, streamErr, "stream aborted before completion") } return cmdutil.WrapHTTP(streamErr, "agent-chat stream") } - // Server closed cleanly but never sent a Done event — treat as aborted + // Server closed cleanly but never sent a complete event — treat as aborted // so agents don't silently emit a truncated answer as ok=true. - if !acc.Done() { + if !projector.Done() { return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event") } - - answer := acc.Answer() - out := iostreams.IO.Out - if streamMode { - if !strings.HasSuffix(answer, "\n") { - fmt.Fprintln(out) - } - } else { - fmt.Fprint(out, answer) - if !strings.HasSuffix(answer, "\n") { - fmt.Fprintln(out) - } - } - renderAskToolTrace(out, acc.ToolEvents) - format.WriteReferences(out, acc.References) - return nil + return renderer.Close() } -// renderAskToolTrace prints a compact tool-event footer in --format text -// mode. Skipped when the agent emitted no tool events — silent beats an -// empty banner. -func renderAskToolTrace(w io.Writer, events []sse.AgentToolEvent) { - if len(events) == 0 { - return +// runAskJSON handles the --format json path (the default): collect the +// projection and emit it in one normal success envelope. +func runAskJSON(ctx context.Context, opts *AskOptions, fopts *cmdutil.FormatOptions, sessionID string, svc AskService) error { + req := &sdk.AgentQARequest{ + Query: opts.Query, + AgentEnabled: true, + AgentID: opts.AgentID, + Channel: "api", } - fmt.Fprintln(w) - fmt.Fprintln(w, "──── Tool trace ────") - for i, e := range events { - fmt.Fprintf(w, "[%d] %s", i+1, e.Kind) - if e.Result != "" { - fmt.Fprintf(w, " %s", truncateAskInline(e.Result, 80)) + + projector := sse.NewProjector(opts.Verbose, opts.Reference, "") + events := make([]sse.ProjectedEvent, 0) + cb := func(r *sdk.AgentStreamResponse) error { + if event, include := projector.Agent(r); include { + events = append(events, event) } - fmt.Fprintln(w) + return nil } + + if err := svc.AgentQAStreamWithRequest(ctx, sessionID, req, cb); err != nil { + if cmdutil.IsCancelled(ctx, err) { + return askStreamError(cmdutil.Wrapf(cmdutil.CodeOperationCancelled, err, "session ask cancelled"), sessionID) + } + return askStreamError(cmdutil.WrapHTTP(err, "agent-chat stream"), sessionID) + } + if !projector.Done() { + return askStreamError( + cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event"), + sessionID, + ) + } + + data := askResult{ + Events: events, + SessionID: sessionID, + AgentID: opts.AgentID, + 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. A nil fopts (direct-test entry) defaults to JSON. + if fopts == nil { + fopts = &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON} + } + return fopts.Emit(iostreams.IO.Out, data, nil) } -// truncateAskInline shrinks a multi-line result to a single line + ellipsis -// for the text tool-trace footer. -func truncateAskInline(s string, maxLen int) string { - s = strings.ReplaceAll(s, "\n", " ") - if len(s) <= maxLen { - return s - } - return s[:maxLen-1] + "…" +func askStreamError(err *cmdutil.Error, sessionID string) *cmdutil.Error { + return err.WithDetail(map[string]any{"session_id": sessionID}) +} + +// askResult is the --format json data payload. The projector controls default +// versus verbose coverage. +type askResult struct { + Events []sse.ProjectedEvent `json:"events"` + SessionID string `json:"session_id"` + AgentID string `json:"agent_id"` + Query string `json:"query"` } // compile-time check: production SDK client satisfies AskService. diff --git a/cli/cmd/session/ask_test.go b/cli/cmd/session/ask_test.go index e67dc464..15735b81 100644 --- a/cli/cmd/session/ask_test.go +++ b/cli/cmd/session/ask_test.go @@ -10,6 +10,7 @@ import ( "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" ) @@ -69,19 +70,19 @@ func textOpts() *cmdutil.FormatOptions { return &cmdutil.FormatOptions{Mode: cmdutil.FormatText} } -// ndjsonOpts returns a FormatOptions for the NDJSON event-stream path. -// --format json routes here too for streaming commands. +// ndjsonOpts returns a FormatOptions for the NDJSON event-stream path +// (--format ndjson: raw SDK agent events, one per line). func ndjsonOpts() *cmdutil.FormatOptions { return &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON} } -// jsonOpts returns a FormatOptions configured for the JSON path. -// In v0.7 --format json routes to the NDJSON stream path for streaming commands. +// jsonOpts returns a FormatOptions configured for the JSON object path +// (--format json: one accumulated {ok,data} envelope). func jsonOpts() *cmdutil.FormatOptions { return &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON} } -// TestSessionAsk_NDJSON_FirstLineIsInit verifies that the NDJSON path (--format json) +// TestSessionAsk_NDJSON_FirstLineIsInit verifies that the NDJSON path (--format ndjson) // always injects an "init" line first, carrying session_id and agent_id. func TestSessionAsk_NDJSON_FirstLineIsInit(t *testing.T) { out, errBuf := iostreams.SetForTest(t) @@ -92,7 +93,7 @@ func TestSessionAsk_NDJSON_FirstLineIsInit(t *testing.T) { }, } opts := &AskOptions{AgentID: "ag_x", Query: "ping"} - if err := runAsk(context.Background(), opts, jsonOpts(), svc); err != nil { + if err := runAsk(context.Background(), opts, ndjsonOpts(), svc); err != nil { t.Fatalf("runAsk: %v", err) } @@ -134,7 +135,7 @@ func TestSessionAsk_NDJSON_PassthroughEvents(t *testing.T) { }, } opts := &AskOptions{AgentID: "ag_x", Query: "hi"} - if err := runAsk(context.Background(), opts, jsonOpts(), svc); err != nil { + if err := runAsk(context.Background(), opts, ndjsonOpts(), svc); err != nil { t.Fatalf("runAsk: %v", err) } @@ -152,29 +153,155 @@ func TestSessionAsk_NDJSON_PassthroughEvents(t *testing.T) { } } -// TestSessionAsk_NDJSON_JSONEqualsNDJSON verifies that --format json and --format ndjson -// produce identical NDJSON streams for session ask. -func TestSessionAsk_NDJSON_JSONEqualsNDJSON(t *testing.T) { - events := []*sdk.AgentStreamResponse{ - answerEvent("hello"), +// TestSessionAsk_FormatJSON_EmitsSingleEnvelope verifies that default JSON +// keeps answer events only. +func TestSessionAsk_FormatJSON_EmitsSingleEnvelope(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{ + // Per-event Done markers are not terminal for the whole agent run. + {ResponseType: sdk.AgentResponseTypeThinking, Content: "hidden reasoning", Done: true}, + toolCallEvent("call_1", "knowledge_search"), + referencesEvent([]*sdk.SearchResult{{ID: "c1", Content: "BULKY PASSAGE", KnowledgeTitle: "Doc"}}), + answerEvent("the answer"), + {ResponseType: sdk.AgentResponseTypeAnswer, Done: true}, doneEvent(), + }} + opts := &AskOptions{AgentID: "ag_x", Query: "hi"} + if err := runAsk(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc); err != nil { + t.Fatalf("runAsk: %v", err) } - - runWith := func(mode cmdutil.FormatMode) string { - out, _ := iostreams.SetForTest(t) - svc := &scriptedAskSvc{events: events} - opts := &AskOptions{AgentID: "ag_x", Query: "q"} - fopts := &cmdutil.FormatOptions{Mode: mode} - if err := runAsk(context.Background(), opts, fopts, svc); err != nil { - t.Fatalf("runAsk(%s): %v", mode, 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"` + AgentID string `json:"agent_id"` + Query string `json:"query"` + } `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") + } + if len(env.Data.Events) != 2 { + t.Fatalf("events=%+v, want two answer frames", env.Data.Events) + } + for i, event := range env.Data.Events { + if event.ResponseType != "answer" { + t.Errorf("events[%d].response_type=%q, want answer", i, event.ResponseType) } - return out.String() } + if env.Data.Events[0].Content != "the answer" { + t.Errorf("answer content=%q", env.Data.Events[0].Content) + } + if env.Data.AgentID != "ag_x" || env.Data.Query != "hi" { + t.Errorf("echo fields: agent_id=%q query=%q", env.Data.AgentID, env.Data.Query) + } + if env.Data.SessionID == "" { + t.Error("session_id empty") + } +} - jsonOut := runWith(cmdutil.FormatJSON) - ndjsonOut := runWith(cmdutil.FormatNDJSON) - if jsonOut != ndjsonOut { - t.Errorf("--format json and --format ndjson differ:\n json: %q\n ndjson: %q", jsonOut, ndjsonOut) +func TestSessionAsk_FormatJSON_VerboseAndReferenceIncludeBothDetailClasses(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{ + {ID: "think", ResponseType: sdk.AgentResponseTypeThinking, Content: "reasoning", Done: true}, + toolCallEvent("call_1", "knowledge_search"), + referencesEvent([]*sdk.SearchResult{{ID: "c1", KnowledgeBaseID: "kb1", ParentChunkID: "p1", Content: "BULK"}}), + answerEvent("answer [chunk:c1]"), + doneEvent(), + }} + opts := &AskOptions{AgentID: "ag_x", Query: "hi", Verbose: true, Reference: true} + if err := runAsk(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc); err != nil { + t.Fatalf("runAsk: %v", err) + } + var env struct { + Data struct { + Events []sse.ProjectedEvent `json:"events"` + } `json:"data"` + } + if err := json.Unmarshal(out.Bytes(), &env); err != nil { + t.Fatal(err) + } + want := []string{"thinking", "tool_call", "references", "answer", "complete"} + if len(env.Data.Events) != len(want) { + t.Fatalf("events=%+v", env.Data.Events) + } + for i, responseType := range want { + if env.Data.Events[i].ResponseType != responseType { + t.Errorf("events[%d]=%q, want %q", i, env.Data.Events[i].ResponseType, responseType) + } + } + refs := env.Data.Events[2].KnowledgeReferences + if len(refs) != 1 || refs[0].KBID != "kb1" || refs[0].ChunkID != "c1" || refs[0].ParentChunkID != "p1" { + t.Errorf("reference indexes=%+v", refs) + } +} + +// TestSessionAsk_Text_VerboseIncludesThinking verifies the --format text path +// honors --verbose: the agent's thinking streams inline with the answer. +// (Regresses the original bug: runAskText ignored opts.Verbose entirely, so +// thinking never appeared in text mode under any flag.) +func TestSessionAsk_Text_VerboseIncludesThinking(t *testing.T) { + out, _ := iostreams.SetForTestWithTTY(t) + svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{ + {ResponseType: sdk.AgentResponseTypeThinking, Content: "REASONING"}, + answerEvent("answer"), + doneEvent(), + }} + opts := &AskOptions{AgentID: "ag_x", Query: "hi", Verbose: true} + if err := runAsk(context.Background(), opts, textOpts(), svc); err != nil { + t.Fatalf("runAsk: %v", err) + } + if !strings.Contains(out.String(), "REASONING") { + t.Errorf("verbose text output missing thinking: %q", out.String()) + } + if !strings.Contains(out.String(), "answer") { + t.Errorf("answer body missing: %q", out.String()) + } +} + +func TestSessionAsk_Text_NonTTYVerboseIncludesThinking(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{ + {ResponseType: sdk.AgentResponseTypeThinking, Content: "REASONING", Done: true}, + answerEvent("answer"), + doneEvent(), + }} + opts := &AskOptions{AgentID: "ag_x", Query: "hi", Verbose: true} + if err := runAsk(context.Background(), opts, textOpts(), svc); err != nil { + t.Fatalf("runAsk: %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) + } +} + +// TestSessionAsk_Text_HidesThinkingByDefault: without --verbose the text path +// must NOT stream the reasoning pass, only the answer. +func TestSessionAsk_Text_HidesThinkingByDefault(t *testing.T) { + out, _ := iostreams.SetForTestWithTTY(t) + svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{ + {ResponseType: sdk.AgentResponseTypeThinking, Content: "REASONING"}, + answerEvent("answer"), + doneEvent(), + }} + opts := &AskOptions{AgentID: "ag_x", Query: "hi"} + if err := runAsk(context.Background(), opts, textOpts(), svc); err != nil { + t.Fatalf("runAsk: %v", err) + } + if strings.Contains(out.String(), "REASONING") { + t.Errorf("non-verbose text output leaked thinking: %q", out.String()) + } + if !strings.Contains(out.String(), "answer") { + t.Errorf("answer body missing: %q", out.String()) } } @@ -280,6 +407,25 @@ func TestSessionAsk_NoDoneEvent_MapsToSSEStreamAborted(t *testing.T) { } } +func TestSessionAsk_FormatJSON_StreamErrorIncludesSessionDetail(t *testing.T) { + _, _ = iostreams.SetForTest(t) + svc := &scriptedAskSvc{streamErr: errors.New("connection reset")} + err := runAsk( + context.Background(), + &AskOptions{AgentID: "ag", Query: "x"}, + jsonOpts(), + 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" { + t.Errorf("error detail=%v, want auto-created session_id", typed.Detail) + } +} + func TestSessionAsk_CreateSessionFails_MapsToSessionCreateFailed(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &scriptedAskSvc{createErr: errors.New("connection refused")} @@ -311,8 +457,8 @@ func TestSessionAsk_Cancellation_MapsToOperationCancelled(t *testing.T) { } } -// Sanity: text-mode output writes the answer body and a tool-trace footer. -func TestSessionAsk_Text_Accumulate_PrintsAnswerAndFooter(t *testing.T) { +// Default text writes answer events but filters tool events. +func TestSessionAsk_Text_DefaultHidesTools(t *testing.T) { out, _ := iostreams.SetForTest(t) svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{ answerEvent("hello"), @@ -327,8 +473,8 @@ func TestSessionAsk_Text_Accumulate_PrintsAnswerAndFooter(t *testing.T) { if !strings.Contains(got, "hello") { t.Errorf("answer body missing: %q", got) } - if !strings.Contains(got, "Tool trace") { - t.Errorf("tool trace footer missing: %q", got) + if strings.Contains(got, "tool_call") || strings.Contains(got, "knowledge_search") { + t.Errorf("default text output leaked tool event: %q", got) } } @@ -437,7 +583,7 @@ func TestSessionAsk_NDJSON_IncludesReferencesViaSDKEvent(t *testing.T) { }, } opts := &AskOptions{AgentID: "ag_x", Query: "ping"} - if err := runAsk(context.Background(), opts, jsonOpts(), svc); err != nil { + if err := runAsk(context.Background(), opts, ndjsonOpts(), svc); err != nil { t.Fatalf("runAsk: %v", err) } @@ -463,3 +609,54 @@ func TestSessionAsk_NDJSON_IncludesReferencesViaSDKEvent(t *testing.T) { t.Errorf("expected references event at line 3, got response_type=%v", refsLine["response_type"]) } } + +func TestSessionAsk_NDJSON_PreservesReferencesAndThinking(t *testing.T) { + // NDJSON is the raw protocol surface: reasoning and full reference payloads + // pass through unchanged. Index projection is limited to JSON/text/MCP. + svc := &scriptedAskSvc{ + events: []*sdk.AgentStreamResponse{ + {ResponseType: sdk.AgentResponseTypeThinking, Content: "reasoning"}, + referencesEvent([]*sdk.SearchResult{{ID: "c1", Content: "BULKY PASSAGE", KnowledgeTitle: "Doc"}}), + answerEvent("hello"), + doneEvent(), + }, + } + out, _ := iostreams.SetForTest(t) + + opts := &AskOptions{AgentID: "ag_x", Query: "hi"} + if err := runAsk(context.Background(), opts, ndjsonOpts(), svc); err != nil { + t.Fatalf("runAsk: %v", err) + } + + var refsLine map[string]any + sawThinking := false + for _, line := range strings.Split(strings.TrimRight(out.String(), "\n"), "\n") { + var ev map[string]any + if err := json.Unmarshal([]byte(line), &ev); err != nil { + continue + } + if ev["response_type"] == "thinking" { + sawThinking = true + } + if ev["response_type"] == "references" { + refsLine = ev + } + } + if !sawThinking { + t.Error("thinking event was filtered from raw NDJSON output") + } + if refsLine == nil { + t.Fatal("references event not emitted") + } + refs, _ := refsLine["knowledge_references"].([]any) + if len(refs) != 1 { + t.Fatalf("knowledge_references=%d, want 1", len(refs)) + } + first, _ := refs[0].(map[string]any) + if first["content"] != "BULKY PASSAGE" { + t.Errorf("references[0].content=%v, want original content", first["content"]) + } + if first["id"] != "c1" { + t.Errorf("references[0].id=%v, want c1", first["id"]) + } +} diff --git a/cli/internal/format/references.go b/cli/internal/format/references.go index 9fdaeff5..4ad88cf9 100644 --- a/cli/internal/format/references.go +++ b/cli/internal/format/references.go @@ -1,37 +1,36 @@ package format -import ( - "fmt" - "io" +import sdk "github.com/Tencent/WeKnora/client" - sdk "github.com/Tencent/WeKnora/client" -) +// ReferenceIndex is the bounded citation pointer exposed by projected JSON, +// text, and MCP output. ChunkID is the chunk the model cited; ParentChunkID is +// retained when callers prefer to fetch the larger self-contained passage. +// Full chunk text and retrieval metadata remain available only in raw NDJSON. +type ReferenceIndex struct { + KBID string `json:"kb_id,omitempty"` + ChunkID string `json:"chunk_id"` + ParentChunkID string `json:"parent_chunk_id,omitempty"` +} -// WriteReferences renders the compact references footer used by chat and -// agent invoke: a horizontal rule, one numbered line per reference, -// best-available title + optional score. Skipped entirely when refs is -// empty - agent-friendly silence beats an empty banner. -func WriteReferences(w io.Writer, refs []*sdk.SearchResult) { - if len(refs) == 0 { - return - } - fmt.Fprintln(w) - fmt.Fprintln(w, "──── References ────") - for i, r := range refs { - if r == nil { +// IndexReferences projects full SDK search results into stable lookup keys. +// It never mutates the SDK events, which keeps the raw NDJSON path lossless. +// fallbackKBID is used by `chat`, whose single KB is known by the CLI even +// when an older server omits knowledge_base_id from a reference. +func IndexReferences(refs []*sdk.SearchResult, fallbackKBID string) []ReferenceIndex { + indexes := make([]ReferenceIndex, 0, len(refs)) + for _, r := range refs { + if r == nil || r.ID == "" { continue } - title := r.KnowledgeTitle - if title == "" { - title = r.KnowledgeFilename + kbID := r.KnowledgeBaseID + if kbID == "" { + kbID = fallbackKBID } - if title == "" { - title = r.KnowledgeID - } - fmt.Fprintf(w, "[%d] %s", i+1, title) - if r.Score > 0 { - fmt.Fprintf(w, " score=%.3f", r.Score) - } - fmt.Fprintln(w) + indexes = append(indexes, ReferenceIndex{ + KBID: kbID, + ChunkID: r.ID, + ParentChunkID: r.ParentChunkID, + }) } + return indexes } diff --git a/cli/internal/format/references_test.go b/cli/internal/format/references_test.go new file mode 100644 index 00000000..dd6b91f7 --- /dev/null +++ b/cli/internal/format/references_test.go @@ -0,0 +1,38 @@ +package format + +import ( + "testing" + + sdk "github.com/Tencent/WeKnora/client" +) + +func TestIndexReferences_ProjectsLookupFieldsWithoutMutation(t *testing.T) { + refs := []*sdk.SearchResult{ + {ID: "c1", Content: "bulky passage one", KnowledgeBaseID: "kb1", ParentChunkID: "p1", KnowledgeTitle: "Doc One", Score: 0.5}, + {ID: "c2", Content: "bulky passage two", ParentChunkID: "p2"}, + nil, + } + got := IndexReferences(refs, "fallback") + + if len(got) != 2 { + t.Fatalf("indexes=%d, want 2", len(got)) + } + if got[0].KBID != "kb1" || got[0].ChunkID != "c1" || got[0].ParentChunkID != "p1" { + t.Errorf("first index=%+v", got[0]) + } + if got[1].KBID != "fallback" || got[1].ChunkID != "c2" { + t.Errorf("fallback index=%+v", got[1]) + } + if refs[0].Content != "bulky passage one" || refs[1].Content != "bulky passage two" { + t.Errorf("source references mutated: %+v", refs) + } +} + +func TestIndexReferences_NilSafe(t *testing.T) { + if got := IndexReferences(nil, ""); len(got) != 0 { + t.Errorf("nil indexes=%+v", got) + } + if got := IndexReferences([]*sdk.SearchResult{nil, nil}, ""); len(got) != 0 { + t.Errorf("nil-entry indexes=%+v", got) + } +} diff --git a/cli/internal/mcp/tools.go b/cli/internal/mcp/tools.go index 81d4f881..f2e91c11 100644 --- a/cli/internal/mcp/tools.go +++ b/cli/internal/mcp/tools.go @@ -431,22 +431,22 @@ type chatInput struct { KBID string `json:"kb_id" jsonschema:"knowledge base ID to chat against"` Query string `json:"query" jsonschema:"user query"` SessionID string `json:"session_id,omitempty" jsonschema:"existing session to continue; auto-created when empty"` + Reference bool `json:"reference,omitempty" jsonschema:"include indexed references"` + Verbose bool `json:"verbose,omitempty" jsonschema:"include reasoning, tools, and lifecycle events"` } type chatOutput struct { - Answer string `json:"answer"` - References []*sdk.SearchResult `json:"references"` - Thinking string `json:"thinking,omitempty"` // reasoning text from response_type=thinking; empty for non-reasoning models - SessionID string `json:"session_id"` - AssistantMessageID string `json:"assistant_message_id,omitempty"` - KBID string `json:"kb_id"` - Query string `json:"query"` + 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"` } func addChat(server *mcpsdk.Server, svc chatService) { mcpsdk.AddTool(server, &mcpsdk.Tool{ Name: "chat", - Description: "Stream a RAG answer from the LLM, grounded in the given knowledge base. The SSE stream is accumulated server-side (MCP tools/call has no standard partial-response, so this is NOT streaming); the tool returns the full accumulated response once the stream completes. Pass session_id to continue a multi-turn conversation; otherwise a fresh session is auto-created.", + Description: "Run a RAG answer against a knowledge base. Returns a bounded answer-event projection by default; reference=true adds indexed citations and verbose=true adds reasoning, tool, and lifecycle events. MCP tools/call is buffered rather than streaming. Pass session_id to continue a conversation.", Annotations: &mcpsdk.ToolAnnotations{ Title: "Chat with KB (Streaming RAG)", DestructiveHint: bptr(false), @@ -475,27 +475,28 @@ func addChat(server *mcpsdk.Server, svc chatService) { AgentEnabled: false, Channel: "api", } - acc := &sse.Accumulator{} + projector := sse.NewProjector(in.Verbose, in.Reference, in.KBID) + events := make([]sse.ProjectedEvent, 0) streamErr := svc.KnowledgeQAStream(ctx, sessionID, req, func(r *sdk.StreamResponse) error { - acc.Append(r) + if event, include := projector.Chat(r); include { + events = append(events, event) + } return nil }) if streamErr != nil { return toolErrorResult(cmdutil.WrapHTTP(streamErr, "knowledge qa stream")), nil, nil } - if !acc.Done() { + if !projector.Done() { return toolErrorResult(cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")), nil, nil } - sid := acc.SessionID + sid := projector.SessionID() if sid == "" { sid = sessionID } return successResult(chatOutput{ - Answer: acc.Result(), - References: acc.References, - Thinking: acc.Thinking(), + Events: events, SessionID: sid, - AssistantMessageID: acc.AssistantMessageID, + AssistantMessageID: projector.AssistantMessageID(), KBID: in.KBID, Query: in.Query, }), nil, nil @@ -539,22 +540,21 @@ type sessionAskInput struct { AgentID string `json:"agent_id" jsonschema:"custom agent ID"` Query string `json:"query" jsonschema:"user query"` SessionID string `json:"session_id,omitempty" jsonschema:"existing session to continue; auto-created when empty"` + Reference bool `json:"reference,omitempty" jsonschema:"include indexed references"` + Verbose bool `json:"verbose,omitempty" jsonschema:"include reasoning, tools, and lifecycle events"` } type sessionAskOutput struct { - Answer string `json:"answer"` - References []*sdk.SearchResult `json:"references"` - ToolEvents []sse.AgentToolEvent `json:"tool_events,omitempty"` - Thinking string `json:"thinking,omitempty"` - SessionID string `json:"session_id"` - AgentID string `json:"agent_id"` - Query string `json:"query"` + Events []sse.ProjectedEvent `json:"events"` + SessionID string `json:"session_id"` + AgentID string `json:"agent_id"` + Query string `json:"query"` } func addSessionAsk(server *mcpsdk.Server, svc sessionAskService) { mcpsdk.AddTool(server, &mcpsdk.Tool{ Name: "session_ask", - Description: "Run a query through a custom agent via `session ask --agent` (system prompt + tool allow-list + KB scope). The agent's SSE stream is accumulated server-side (MCP tools/call has no standard partial-response, so this is NOT streaming); the tool returns the final accumulated response once the stream completes.", + Description: "Run a query through a custom agent. Returns a bounded answer-event projection by default; reference=true adds indexed citations and verbose=true adds reasoning, tool, and lifecycle events. MCP tools/call is buffered rather than streaming.", Annotations: &mcpsdk.ToolAnnotations{ Title: "Ask a Custom Agent (session ask --agent)", DestructiveHint: bptr(false), @@ -569,7 +569,8 @@ func addSessionAsk(server *mcpsdk.Server, svc sessionAskService) { if strings.TrimSpace(in.Query) == "" { return toolErrorResult(cmdutil.NewError(cmdutil.CodeInputMissingFlag, "query cannot be empty")), nil, nil } - acc := &sse.AgentAccumulator{} + projector := sse.NewProjector(in.Verbose, in.Reference, "") + events := make([]sse.ProjectedEvent, 0) req := &sdk.AgentQARequest{ Query: in.Query, AgentEnabled: true, @@ -587,23 +588,22 @@ func addSessionAsk(server *mcpsdk.Server, svc sessionAskService) { sessionID = sess.ID } streamErr := svc.AgentQAStreamWithRequest(ctx, sessionID, req, func(r *sdk.AgentStreamResponse) error { - acc.Append(r) + if event, include := projector.Agent(r); include { + events = append(events, event) + } return nil }) if streamErr != nil { return toolErrorResult(cmdutil.WrapHTTP(streamErr, "agent-chat stream")), nil, nil } - if !acc.Done() { + if !projector.Done() { return toolErrorResult(cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")), nil, nil } return successResult(sessionAskOutput{ - Answer: acc.Answer(), - References: acc.References, - ToolEvents: acc.ToolEvents, - Thinking: acc.Thinking(), - SessionID: sessionID, - AgentID: in.AgentID, - Query: in.Query, + Events: events, + SessionID: sessionID, + AgentID: in.AgentID, + Query: in.Query, }), nil, nil }) } diff --git a/cli/internal/mcp/tools_test.go b/cli/internal/mcp/tools_test.go index c75401f2..a386b862 100644 --- a/cli/internal/mcp/tools_test.go +++ b/cli/internal/mcp/tools_test.go @@ -423,30 +423,37 @@ func TestTool_SearchChunks_PassesMatchCountFromLimit(t *testing.T) { assert.Equal(t, 50, svc.calls.hybridParams.MatchCount, "MCP search_chunks must thread limit into SearchParams.MatchCount") } -func TestTool_Chat_AccumulateAnswerAndReferences(t *testing.T) { +func TestTool_Chat_DefaultReturnsAnswerEventsOnly(t *testing.T) { svc := &fakeSvc{ kbStreamEvents: []*sdk.StreamResponse{ {Content: "Hello "}, {Content: "world."}, - {KnowledgeReferences: []*sdk.SearchResult{{KnowledgeID: "k1"}}}, + {KnowledgeReferences: []*sdk.SearchResult{{ + ID: "c1", + KnowledgeID: "k1", + ParentChunkID: "p1", + Content: "bulky passage", + }}}, {ResponseType: sdk.ResponseTypeComplete}, }, } c, _ := newTestServer(t, svc) var out chatOutput callTool(t, c, "chat", map[string]any{"kb_id": "kb_x", "query": "ping"}, &out) - if out.Answer != "Hello world." { - t.Errorf("answer = %q", out.Answer) + if len(out.Events) != 2 || out.Events[0].Content != "Hello " || out.Events[1].Content != "world." { + t.Errorf("answer events=%+v", out.Events) } - if len(out.References) != 1 || out.References[0].KnowledgeID != "k1" { - t.Errorf("references missing: %+v", out.References) + for _, event := range out.Events { + if event.ResponseType != "answer" || len(event.KnowledgeReferences) != 0 { + t.Errorf("default output leaked non-answer data: %+v", event) + } } if out.SessionID != "sess_auto" { t.Errorf("session_id = %q, want sess_auto", out.SessionID) } } -func TestMCP_ChatToolReturnsThinking(t *testing.T) { +func TestMCP_ChatVerbosePreservesThinking(t *testing.T) { svc := &fakeSvc{ kbStreamEvents: []*sdk.StreamResponse{ {ResponseType: sdk.ResponseTypeThinking, Content: "let me reason..."}, @@ -456,12 +463,15 @@ func TestMCP_ChatToolReturnsThinking(t *testing.T) { } c, _ := newTestServer(t, svc) var out chatOutput - callTool(t, c, "chat", map[string]any{"kb_id": "kb_x", "query": "deep question"}, &out) - if out.Thinking != "let me reason..." { - t.Errorf("thinking = %q, want %q", out.Thinking, "let me reason...") + callTool(t, c, "chat", map[string]any{"kb_id": "kb_x", "query": "deep question", "verbose": true}, &out) + want := []string{"thinking", "answer", "complete"} + if len(out.Events) != len(want) { + t.Fatalf("events=%+v", out.Events) } - if out.Answer != "final answer" { - t.Errorf("answer = %q, want %q", out.Answer, "final answer") + for i, responseType := range want { + if out.Events[i].ResponseType != responseType { + t.Errorf("events[%d]=%q, want %q", i, out.Events[i].ResponseType, responseType) + } } if out.KBID != "kb_x" { t.Errorf("kb_id = %q, want %q", out.KBID, "kb_x") @@ -471,23 +481,35 @@ func TestMCP_ChatToolReturnsThinking(t *testing.T) { } } -func TestMCP_SessionAskToolReturnsToolCalls(t *testing.T) { +func TestMCP_SessionAskVerboseAndReferenceReturnsBothDetailClasses(t *testing.T) { svc := &fakeSvc{ agentEvents: []*sdk.AgentStreamResponse{ {ResponseType: sdk.AgentResponseTypeThinking, Content: "agent thinks"}, {ResponseType: sdk.AgentResponseTypeToolCall, ID: "tc1", Content: "knowledge_search"}, + {ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ + ID: "c1", + ParentChunkID: "p1", + Content: "bulky passage", + }}}, {ResponseType: sdk.AgentResponseTypeAnswer, Content: "agent answer"}, {ResponseType: sdk.AgentResponseTypeComplete, Done: true}, }, } c, _ := newTestServer(t, svc) var out sessionAskOutput - callTool(t, c, "session_ask", map[string]any{"agent_id": "ag1", "query": "tool question"}, &out) - if out.Thinking != "agent thinks" { - t.Errorf("thinking = %q, want %q", out.Thinking, "agent thinks") + callTool(t, c, "session_ask", map[string]any{"agent_id": "ag1", "query": "tool question", "verbose": true, "reference": true}, &out) + want := []string{"thinking", "tool_call", "references", "answer", "complete"} + if len(out.Events) != len(want) { + t.Fatalf("events=%+v", out.Events) } - if len(out.ToolEvents) != 1 || out.ToolEvents[0].ID != "tc1" { - t.Errorf("tool_events = %+v, want 1 event with id tc1", out.ToolEvents) + for i, responseType := range want { + if out.Events[i].ResponseType != responseType { + t.Errorf("events[%d]=%q, want %q", i, out.Events[i].ResponseType, responseType) + } + } + refs := out.Events[2].KnowledgeReferences + if len(refs) != 1 || refs[0].ChunkID != "c1" || refs[0].ParentChunkID != "p1" { + t.Errorf("reference indexes=%+v", refs) } if out.Query != "tool question" { t.Errorf("query = %q, want %q", out.Query, "tool question") @@ -529,11 +551,8 @@ func TestTool_SessionAsk(t *testing.T) { c, _ := newTestServer(t, svc) var out sessionAskOutput callTool(t, c, "session_ask", map[string]any{"agent_id": "ag1", "query": "x"}, &out) - if out.Answer != "result" { - t.Errorf("answer = %q", out.Answer) - } - if len(out.ToolEvents) != 1 { - t.Errorf("tool_calls len = %d, want 1", len(out.ToolEvents)) + if len(out.Events) != 1 || out.Events[0].ResponseType != "answer" || out.Events[0].Content != "result" { + t.Errorf("default events=%+v", out.Events) } if out.AgentID != "ag1" { t.Errorf("agent_id = %q", out.AgentID) diff --git a/cli/internal/sse/accumulator.go b/cli/internal/sse/accumulator.go index 26546402..28e24b95 100644 --- a/cli/internal/sse/accumulator.go +++ b/cli/internal/sse/accumulator.go @@ -65,7 +65,12 @@ func (a *Accumulator) Append(r *sdk.StreamResponse) { a.AssistantMessageID = r.AssistantMessageID } // Capture references whenever they arrive - they may land on a - // dedicated `references` event before the terminal `complete`. + // dedicated `references` event before the terminal `complete`. Strip the + // bulky per-chunk Content so the buffered envelope stays small: agents + // consume the index (id / parent_chunk_id / title / score / snippet) and + // fetch full passages on demand via `chunk view`. This runs after SSE + // parsing, so it governs outgoing envelope size — the incoming line-size + // limit is the scanner buffer's job, not this one. if r.KnowledgeReferences != nil { a.References = r.KnowledgeReferences } diff --git a/cli/internal/sse/agent_accumulator_test.go b/cli/internal/sse/agent_accumulator_test.go index 1dae149f..b0652be8 100644 --- a/cli/internal/sse/agent_accumulator_test.go +++ b/cli/internal/sse/agent_accumulator_test.go @@ -13,6 +13,9 @@ func TestAgentAccumulator_FinalizesOnlyOnComplete(t *testing.T) { {ResponseType: sdk.AgentResponseTypeThinking, Content: "think", Done: true}, {ResponseType: sdk.AgentResponseTypeToolCall, ID: "call_1", Content: "search"}, {ResponseType: sdk.AgentResponseTypeReflection, Content: "reflect", Done: true}, + {ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{ + {ID: "chunk_1", Content: "bulky passage"}, + }}, {ResponseType: sdk.AgentResponseTypeAnswer, Content: "final answer", Done: true}, } for _, event := range preTerminal { @@ -35,6 +38,9 @@ func TestAgentAccumulator_FinalizesOnlyOnComplete(t *testing.T) { if len(a.ToolEvents) != 1 { t.Errorf("tool_events=%d, want 1", len(a.ToolEvents)) } + if len(a.References) != 1 || a.References[0].Content != "bulky passage" { + t.Errorf("references were not preserved: %+v", a.References) + } a.Append(&sdk.AgentStreamResponse{ResponseType: sdk.AgentResponseTypeAnswer, Content: "late"}) if got := a.Answer(); got != "final answer" { diff --git a/cli/internal/sse/projector.go b/cli/internal/sse/projector.go new file mode 100644 index 00000000..b2d30110 --- /dev/null +++ b/cli/internal/sse/projector.go @@ -0,0 +1,283 @@ +package sse + +import ( + "encoding/json" + "fmt" + "io" + "strings" + + "github.com/Tencent/WeKnora/cli/internal/format" + sdk "github.com/Tencent/WeKnora/client" +) + +// ProjectedEvent is the bounded event representation shared by +// buffered JSON, human-readable text, and MCP tool results. It deliberately +// mirrors the SDK field names so consumers can move between projected JSON and +// raw NDJSON without learning a second event vocabulary. +type ProjectedEvent struct { + ID string `json:"id,omitempty"` + ResponseType string `json:"response_type"` + Content string `json:"content,omitempty"` + Done bool `json:"done"` + KnowledgeReferences []format.ReferenceIndex `json:"knowledge_references,omitempty"` + SessionID string `json:"session_id,omitempty"` + AssistantMessageID string `json:"assistant_message_id,omitempty"` + ToolCalls []sdk.LLMToolCall `json:"tool_calls,omitempty"` + Data map[string]any `json:"data,omitempty"` +} + +// Projector observes every SDK frame for lifecycle state, then returns the +// presentation event selected by the output contract. Default output keeps +// answer frames only. Reference enables bounded citation events; verbose +// enables execution and lifecycle events. +type Projector struct { + verbose bool + reference bool + fallbackKBID string + seen bool + done bool + sessionID string + assistantMessageID string +} + +func NewProjector(verbose, reference bool, fallbackKBID string) *Projector { + return &Projector{verbose: verbose, reference: reference, fallbackKBID: fallbackKBID} +} + +func (p *Projector) Seen() bool { return p.seen } +func (p *Projector) Done() bool { return p.done } +func (p *Projector) SessionID() string { return p.sessionID } +func (p *Projector) AssistantMessageID() string { return p.assistantMessageID } + +// Chat consumes one KnowledgeQAStream frame. +func (p *Projector) Chat(r *sdk.StreamResponse) (ProjectedEvent, bool) { + if r == nil || p.done { + return ProjectedEvent{}, false + } + p.seen = true + if p.sessionID == "" && r.SessionID != "" { + p.sessionID = r.SessionID + } + if p.assistantMessageID == "" && r.AssistantMessageID != "" { + p.assistantMessageID = r.AssistantMessageID + } + if r.ResponseType == sdk.ResponseTypeComplete { + p.done = true + } + + responseType := string(r.ResponseType) + isAnswer := r.ResponseType == sdk.ResponseTypeAnswer || (r.ResponseType == "" && r.Content != "") + isReference := r.ResponseType == sdk.ResponseTypeReferences + include := isAnswer || (p.verbose && !isReference) || (p.reference && isReference) + if !include && p.reference && len(r.KnowledgeReferences) > 0 { + return p.chatReferenceEvent(r), true + } + if !include { + return ProjectedEvent{}, false + } + if responseType == "" { + responseType = string(sdk.ResponseTypeAnswer) + } + event := ProjectedEvent{ + ID: r.ID, + ResponseType: responseType, + Content: r.Content, + Done: r.Done, + SessionID: r.SessionID, + AssistantMessageID: r.AssistantMessageID, + ToolCalls: r.ToolCalls, + Data: r.Data, + } + if p.reference { + event.KnowledgeReferences = format.IndexReferences(r.KnowledgeReferences, p.fallbackKBID) + } + return event, true +} + +// Agent consumes one AgentQAStream frame. +func (p *Projector) Agent(r *sdk.AgentStreamResponse) (ProjectedEvent, bool) { + if r == nil || p.done { + return ProjectedEvent{}, false + } + p.seen = true + if r.ResponseType == sdk.AgentResponseTypeComplete { + p.done = true + } + + isAnswer := r.ResponseType == sdk.AgentResponseTypeAnswer + isReference := r.ResponseType == sdk.AgentResponseTypeReferences + include := isAnswer || (p.verbose && !isReference) || (p.reference && isReference) + if !include && p.reference && len(r.KnowledgeReferences) > 0 { + return p.agentReferenceEvent(r), true + } + if !include { + return ProjectedEvent{}, false + } + event := ProjectedEvent{ + ID: r.ID, + ResponseType: string(r.ResponseType), + Content: r.Content, + Done: r.Done, + Data: r.Data, + } + if p.reference { + event.KnowledgeReferences = format.IndexReferences(r.KnowledgeReferences, p.fallbackKBID) + } + return event, true +} + +func (p *Projector) chatReferenceEvent(r *sdk.StreamResponse) ProjectedEvent { + return ProjectedEvent{ + ID: r.ID, + ResponseType: string(sdk.ResponseTypeReferences), + Done: r.Done, + KnowledgeReferences: format.IndexReferences(r.KnowledgeReferences, p.fallbackKBID), + SessionID: r.SessionID, + AssistantMessageID: r.AssistantMessageID, + } +} + +func (p *Projector) agentReferenceEvent(r *sdk.AgentStreamResponse) ProjectedEvent { + return ProjectedEvent{ + ID: r.ID, + ResponseType: string(sdk.AgentResponseTypeReferences), + Done: r.Done, + KnowledgeReferences: format.IndexReferences(r.KnowledgeReferences, p.fallbackKBID), + } +} + +// TextRenderer writes projected events as a human-readable stream. +// TTY detection is intentionally absent: terminals and pipes receive the same +// filtering semantics; callers may add styling later without changing them. +type TextRenderer struct { + w io.Writer + verbose bool + lastKey string + atBOL bool +} + +func NewTextRenderer(w io.Writer, verbose bool) *TextRenderer { + return &TextRenderer{w: w, verbose: verbose, atBOL: true} +} + +func (r *TextRenderer) Write(ev ProjectedEvent) error { + switch ev.ResponseType { + case string(sdk.ResponseTypeAnswer): + return r.writeContentBlock(ev, "answer") + case string(sdk.ResponseTypeThinking), string(sdk.ResponseTypeReflection): + return r.writeContentBlock(ev, ev.ResponseType) + case string(sdk.ResponseTypeReferences): + return r.writeReferences(ev) + default: + return r.writeStructured(ev) + } +} + +func (r *TextRenderer) Close() error { + if !r.atBOL { + return r.writeString("\n") + } + return nil +} + +func (r *TextRenderer) writeContentBlock(ev ProjectedEvent, label string) error { + key := ev.ResponseType + "\x00" + ev.ID + if key != r.lastKey { + if err := r.ensureBOL(); err != nil { + return err + } + if r.verbose { + if err := r.writeString("[" + label + "]\n"); err != nil { + return err + } + } + r.lastKey = key + } + if ev.Content != "" { + if err := r.writeString(ev.Content); err != nil { + return err + } + } + if ev.Done { + r.lastKey = "" + return r.ensureBOL() + } + return nil +} + +func (r *TextRenderer) writeReferences(ev ProjectedEvent) error { + if err := r.ensureBOL(); err != nil { + return err + } + if err := r.writeString("[references]\n"); err != nil { + return err + } + for _, ref := range ev.KnowledgeReferences { + line := "- chunk_id=" + ref.ChunkID + if ref.KBID != "" { + line += " kb_id=" + ref.KBID + } + if ref.ParentChunkID != "" { + line += " parent_chunk_id=" + ref.ParentChunkID + } + if err := r.writeString(line + "\n"); err != nil { + return err + } + } + r.lastKey = "" + return nil +} + +func (r *TextRenderer) writeStructured(ev ProjectedEvent) error { + if err := r.ensureBOL(); err != nil { + return err + } + header := "[" + ev.ResponseType + if ev.ID != "" { + header += " " + ev.ID + } + header += "]" + if err := r.writeString(header); err != nil { + return err + } + if ev.Content != "" { + if err := r.writeString(" " + strings.ReplaceAll(ev.Content, "\n", " ")); err != nil { + return err + } + } + if len(ev.ToolCalls) > 0 { + b, _ := json.Marshal(ev.ToolCalls) + if err := r.writeString(" " + string(b)); err != nil { + return err + } + } + if len(ev.Data) > 0 { + b, _ := json.Marshal(ev.Data) + if err := r.writeString(" " + string(b)); err != nil { + return err + } + } + if err := r.writeString("\n"); err != nil { + return err + } + r.lastKey = "" + return nil +} + +func (r *TextRenderer) ensureBOL() error { + if r.atBOL { + return nil + } + return r.writeString("\n") +} + +func (r *TextRenderer) writeString(s string) error { + if s == "" { + return nil + } + if _, err := fmt.Fprint(r.w, s); err != nil { + return err + } + r.atBOL = strings.HasSuffix(s, "\n") + return nil +} diff --git a/cli/internal/sse/projector_test.go b/cli/internal/sse/projector_test.go new file mode 100644 index 00000000..b52a5e0c --- /dev/null +++ b/cli/internal/sse/projector_test.go @@ -0,0 +1,137 @@ +package sse_test + +import ( + "bytes" + "strings" + "testing" + + "github.com/Tencent/WeKnora/cli/internal/sse" + sdk "github.com/Tencent/WeKnora/client" +) + +func TestProjector_DefaultKeepsOnlyAnswerEvents(t *testing.T) { + p := sse.NewProjector(false, false, "kb_fallback") + input := []*sdk.StreamResponse{ + {ID: "think", ResponseType: sdk.ResponseTypeThinking, Content: "hidden"}, + {ID: "a", ResponseType: sdk.ResponseTypeAnswer, Content: "one", KnowledgeReferences: []*sdk.SearchResult{{ID: "piggyback", Content: "bulk"}}}, + {ID: "refs", ResponseType: sdk.ResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ID: "c1", Content: "bulk"}}}, + {ID: "a", ResponseType: sdk.ResponseTypeAnswer, Content: "two", Done: true}, + {ResponseType: sdk.ResponseTypeComplete, Done: true}, + } + var got []sse.ProjectedEvent + for _, event := range input { + if projected, ok := p.Chat(event); ok { + got = append(got, projected) + } + } + if !p.Done() || len(got) != 2 { + t.Fatalf("done=%v events=%+v", p.Done(), got) + } + if got[0].Content != "one" || got[1].Content != "two" { + t.Errorf("answer order changed: %+v", got) + } + if len(got[0].KnowledgeReferences) != 0 { + t.Errorf("default answer leaked piggyback references: %+v", got[0]) + } +} + +func TestProjector_VerboseAndReferenceIncludeBothDetailClasses(t *testing.T) { + p := sse.NewProjector(true, true, "kb_fallback") + input := []*sdk.AgentStreamResponse{ + {ID: "t", ResponseType: sdk.AgentResponseTypeThinking, Content: "think"}, + {ID: "call", ResponseType: sdk.AgentResponseTypeToolCall, Content: "search"}, + {ID: "refs", ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ID: "c1", KnowledgeBaseID: "kb1", ParentChunkID: "p1", Content: "bulk"}}}, + {ID: "a", ResponseType: sdk.AgentResponseTypeAnswer, Content: "answer"}, + {ResponseType: sdk.AgentResponseTypeComplete, Done: true}, + } + var got []sse.ProjectedEvent + for _, event := range input { + if projected, ok := p.Agent(event); ok { + got = append(got, projected) + } + } + want := []string{"thinking", "tool_call", "references", "answer", "complete"} + if len(got) != len(want) { + t.Fatalf("events=%+v", got) + } + for i := range want { + if got[i].ResponseType != want[i] { + t.Errorf("event[%d]=%q, want %q", i, got[i].ResponseType, want[i]) + } + } + refs := got[2].KnowledgeReferences + if len(refs) != 1 || refs[0].KBID != "kb1" || refs[0].ChunkID != "c1" || refs[0].ParentChunkID != "p1" { + t.Errorf("reference index=%+v", refs) + } + if input[2].KnowledgeReferences[0].Content != "bulk" { + t.Error("projection mutated the raw SDK event") + } +} + +func TestProjector_ReferenceOnlyAddsIndexesWithoutExecutionTrace(t *testing.T) { + p := sse.NewProjector(false, true, "kb_fallback") + input := []*sdk.AgentStreamResponse{ + {ID: "think", ResponseType: sdk.AgentResponseTypeThinking, Content: "hidden"}, + {ID: "refs", ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ID: "c1", KnowledgeBaseID: "kb1", Content: "bulk"}}}, + {ID: "answer", ResponseType: sdk.AgentResponseTypeAnswer, Content: "answer"}, + {ResponseType: sdk.AgentResponseTypeComplete, Done: true}, + } + var got []sse.ProjectedEvent + for _, event := range input { + if projected, ok := p.Agent(event); ok { + got = append(got, projected) + } + } + if len(got) != 2 || got[0].ResponseType != "references" || got[1].ResponseType != "answer" { + t.Fatalf("reference-only events=%+v", got) + } + if len(got[0].KnowledgeReferences) != 1 || got[0].KnowledgeReferences[0].ChunkID != "c1" { + t.Errorf("reference indexes=%+v", got[0].KnowledgeReferences) + } +} + +func TestProjector_VerboseDoesNotImplicitlyAddReferences(t *testing.T) { + p := sse.NewProjector(true, false, "kb") + input := []*sdk.AgentStreamResponse{ + {ResponseType: sdk.AgentResponseTypeThinking, Content: "thinking"}, + {ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ID: "c1"}}}, + {ResponseType: sdk.AgentResponseTypeAnswer, Content: "answer"}, + {ResponseType: sdk.AgentResponseTypeComplete, Done: true}, + } + var got []sse.ProjectedEvent + for _, event := range input { + if projected, ok := p.Agent(event); ok { + got = append(got, projected) + } + } + for _, event := range got { + if event.ResponseType == "references" || len(event.KnowledgeReferences) != 0 { + t.Fatalf("verbose leaked references without reference=true: %+v", got) + } + } +} + +func TestTextRenderer_StreamsSelectedEvents(t *testing.T) { + var out bytes.Buffer + r := sse.NewTextRenderer(&out, true) + events := []sse.ProjectedEvent{ + {ID: "t", ResponseType: "thinking", Content: "THINK", Done: true}, + {ID: "call", ResponseType: "tool_call", Content: "SEARCH"}, + {ID: "a", ResponseType: "answer", Content: "ANSWER", Done: true}, + } + for _, event := range events { + if err := r.Write(event); err != nil { + t.Fatal(err) + } + } + if err := r.Close(); err != nil { + t.Fatal(err) + } + got := out.String() + thinking := strings.Index(got, "THINK") + tool := strings.Index(got, "SEARCH") + answer := strings.Index(got, "ANSWER") + if !(thinking >= 0 && thinking < tool && tool < answer) { + t.Errorf("event order changed: %q", got) + } +} diff --git a/cli/skills/weknora-rag-search/SKILL.md b/cli/skills/weknora-rag-search/SKILL.md index 5f83745b..54a5662c 100644 --- a/cli/skills/weknora-rag-search/SKILL.md +++ b/cli/skills/weknora-rag-search/SKILL.md @@ -17,8 +17,8 @@ one wastes turns or returns the wrong shape. Use the decision table. | Your goal | Command | LLM synthesis? | Returns | |---|---|---|---| -| Natural-language **answer** grounded in a KB | `chat "" --kb ` | yes | streaming answer + references | -| Answer via a **custom agent** (its own KB scope, tools, web search) | `session ask --agent ""` | yes (+ tools) | streaming answer + tool events | +| Natural-language **answer** grounded in a KB | `chat "" --kb ` | yes | bounded answer events; `--reference` adds citations; `--verbose` adds execution detail | +| Answer via a **custom agent** (its own KB scope, tools, web search) | `session ask --agent ""` | yes (+ tools) | bounded answer events; `--reference` adds citations; `--verbose` adds execution detail | | **Raw context chunks** to reason over yourself (no answer) | `search chunks "" --kb ` | no | ranked chunk list | | Which **documents** match a keyword (title/filename) | `search docs "" --kb ` | no | document list | | Find a **knowledge base** by name | `search kb ""` | no | KB list | @@ -33,9 +33,9 @@ one wastes turns or returns the wrong shape. Use the decision table. ` = invoke a *configured custom agent* (it may scope its own KBs, call tools, do web search). If the user set up an agent for this, prefer it (`weknora agent list` to find ids); otherwise `chat`. -3. **One-shot vs multi-turn.** Both `chat` and `session ask` print an `init` - event with a `session_id`. Pass `--session ` on the next call to continue - the conversation. See `references/chat.md`. +3. **One-shot vs multi-turn.** Both `chat` and `session ask` return a + `data.session_id` in default JSON output. Pass `--session ` on the next + call to continue the conversation. In NDJSON mode, read it from `init`. ## Safety / Gotchas @@ -44,12 +44,14 @@ one wastes turns or returns the wrong shape. Use the decision table. If none resolves it's exit 1 (`local.kb_id_required`); a bad name is exit 1 (`local.kb_not_found`). Resolve names with `weknora kb list` / `search kb`. (`search kb` / `search sessions` are tenant-wide and take no `--kb`.) -- `chat` / `session ask` stream **NDJSON** by default. Parse line-by-line; keep - the `init` event's `session_id` **and** `message_id`. Use `--format text` only - for a human transcript. +- `chat` / `session ask` return one buffered JSON envelope with answer + events by default. Add `--reference` for indexed citations and `--verbose` + for execution detail; use `--format ndjson` for raw events or `--format + text` for the live human-readable projection. - A stalled stream is not stopped by Ctrl-C (that just drops your local connection; the server keeps generating + billing). Stop it server-side: - `weknora session stop --message ` (ids from `init`). + `weknora session stop --message ` (session_id from + `data.session_id`, or from `init` under `--format ndjson`). Re-attach to a stream with `weknora session continue-stream --message `. - `search chunks --limit` defaults to **8** (tuned for an LLM context window); @@ -66,7 +68,7 @@ weknora search chunks "retry backoff policy" --kb engineering --limit 12 # grounded answer (human transcript) weknora chat "How do we handle retries?" --kb engineering --format text -# continue the conversation (session id from the prior init event) +# continue the conversation (session id from data.session_id above) weknora chat "And the max attempts?" --kb engineering --session sess_abc # answer via a custom agent diff --git a/cli/skills/weknora-rag-search/references/chat.md b/cli/skills/weknora-rag-search/references/chat.md index af578555..25bb118a 100644 --- a/cli/skills/weknora-rag-search/references/chat.md +++ b/cli/skills/weknora-rag-search/references/chat.md @@ -1,8 +1,9 @@ -# `chat` and `session ask` — streaming RAG +# `chat` and `session ask` — RAG answers and raw streams -Both stream an NDJSON event log (one JSON object per line) by default. They share -the same event vocabulary; `chat` does plain KB RAG, `session ask` invokes a -custom agent. +Both return one buffered JSON envelope with answer events by default. +`--reference` adds lookup-index references; `--verbose` adds execution events. +They share the raw SSE vocabulary under `--format ndjson`; `chat` does plain KB +RAG, `session ask` invokes a custom agent. ## Commands & flags @@ -13,15 +14,20 @@ weknora session ask "" --agent [--session ] - `--kb` (chat) is required name-or-id. `--agent` (session ask) is required. - `--session ` continues an existing conversation; omit to start a new one. -- `--format text` renders a human transcript instead of NDJSON; `--format json` - / `--format ndjson` both produce the NDJSON stream (identical here). +- `--format json` returns one `{ok,data:{events:[...]}}` envelope; `--format + text` streams the same projection as readable text; `--format ndjson` emits + the raw event stream. +- `--reference` adds bounded reference indexes to JSON/text. +- `--verbose` adds thinking, reflection, tool, metadata, and lifecycle events. +- Combine them when both provenance and execution detail are needed. -## Event stream +## Event stream (`--format ndjson`) -The CLI emits an `init` line first, then passes SDK events through verbatim: +Under `--format ndjson`, the CLI emits an `init` line first, then passes SDK +events through verbatim: ```jsonc -{"event":"init","session_id":"sess_abc","message_id":"msg_xyz","profile":"prod"} +{"type":"init","session_id":"sess_abc","kb_id":"…","profile":"prod"} // session ask: agent_id instead of kb_id {"response_type":"thinking","content":"…"} {"response_type":"tool_call","tool_calls":[…]} // agent only {"response_type":"tool_result","content":"…"} // agent only @@ -32,9 +38,9 @@ The CLI emits an `init` line first, then passes SDK events through verbatim: - Accumulate `response_type:"answer"` `content` pieces for the final answer. - `knowledge_references` carry the grounding chunks (source attribution). -- **Keep `init.session_id` and `init.message_id`**: `session_id` continues the - chat (`--session`); `message_id` is needed to `session stop` or - `session continue-stream` that specific message. +- **Keep `init.session_id`** to continue the chat (`--session`). The + `assistant_message_id` needed for `session stop` / `session continue-stream` + rides on the SDK's `agent_query` frame, not on `init` — scan for it. - On failure mid-stream you get `response_type:"error"`; a transport/HTTP error surfaces as the normal error envelope on stderr with a typed code. diff --git a/cli/skills/weknora-shared/SKILL.md b/cli/skills/weknora-shared/SKILL.md index 80b9da28..82f1139b 100644 --- a/cli/skills/weknora-shared/SKILL.md +++ b/cli/skills/weknora-shared/SKILL.md @@ -57,9 +57,11 @@ Default output is `--format json`: a single envelope. - `error.type` is a **stable typed code** (e.g. `local.kb_not_found`, `input.invalid_argument`, `input.confirmation_required`, `server.error`). Branch on it; `error.hint` usually tells you the next action. -- `--format text` = human output. Streaming commands (`chat`, `session ask`, - `session continue-stream`) emit **NDJSON event lines** by default — expect a - stream, not one blob; use `--format text` for a rendered transcript. +- `--format text` = a live human-readable projection. `chat` and `session ask` + buffer a bounded answer-event projection into one JSON envelope by default; + pass `--reference` for indexed citations, `--verbose` for execution detail, + or `--format ndjson` for raw event lines. `session continue-stream` remains + an NDJSON streaming command. - `--jq ''` filters the envelope (e.g. `weknora kb list --jq '.data[].id'`). - Exception: `weknora auth token` emits the **raw token** by default (it's a scripting helper); pass `--format json` for the `{token, mode, profile}` envelope. @@ -165,5 +167,5 @@ that to learn a command without scraping the human help table. | `weknora auth login` before any profile exists | `profile add --host --use` first (§1) | | Expecting `auth login --host/--name` flags | Gone — host comes from the profile; use global `--profile` | | Auto-adding `-y` to clear an exit-10 | Never; get user approval first (§5) | -| `weknora chat "..."` prints "garbled" stream | NDJSON by default; use `--format text` for a transcript | +| Need the raw `chat` event stream | pass `--format ndjson`; use `--format text` for a live projected transcript | | `search chunks "q"` → exit 1 `local.kb_id_required` | Pass `--kb `, set `WEKNORA_KB_ID`, or `weknora link` the dir |