feat(cli)!: add agent-first chat and session ask output modes

This commit is contained in:
coconut-yc
2026-06-21 02:41:36 +08:00
committed by lyingbug
parent 238297e2c5
commit 9437e1ac3c
18 changed files with 1317 additions and 355 deletions
+13 -7
View File
@@ -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
+25 -1
View File
@@ -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 <chunk_id>` or `chunk view <parent_chunk_id>`.
- 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
+4 -2
View File
@@ -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 <name>` for
single-shot profile overrides without disk writes.
- `weknora mcp serve` exposes a curated read-only tool surface over
+135 -71
View File
@@ -1,21 +1,22 @@
// Package chat implements `weknora chat <text>` - 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.
+198 -53
View File
@@ -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)
}
}
+106 -79
View File
@@ -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.
+227 -30
View File
@@ -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"])
}
}
+27 -28
View File
@@ -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
}
+38
View File
@@ -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)
}
}
+34 -34
View File
@@ -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
})
}
+42 -23
View File
@@ -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)
+6 -1
View File
@@ -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
}
@@ -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" {
+283
View File
@@ -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
}
+137
View File
@@ -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)
}
}
+12 -10
View File
@@ -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 "<q>" --kb <kb>` | yes | streaming answer + references |
| Answer via a **custom agent** (its own KB scope, tools, web search) | `session ask --agent <id> "<q>"` | yes (+ tools) | streaming answer + tool events |
| Natural-language **answer** grounded in a KB | `chat "<q>" --kb <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 <id> "<q>"` | yes (+ tools) | bounded answer events; `--reference` adds citations; `--verbose` adds execution detail |
| **Raw context chunks** to reason over yourself (no answer) | `search chunks "<q>" --kb <kb>` | no | ranked chunk list |
| Which **documents** match a keyword (title/filename) | `search docs "<q>" --kb <kb>` | no | document list |
| Find a **knowledge base** by name | `search kb "<q>"` | no | KB list |
@@ -33,9 +33,9 @@ one wastes turns or returns the wrong shape. Use the decision table.
<id>` = 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 <id>` 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 <id>` 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 <session-id> --message <message-id>` (ids from `init`).
`weknora session stop <session-id> --message <message-id>` (session_id from
`data.session_id`, or from `init` under `--format ndjson`).
Re-attach to a stream with `weknora session continue-stream <session-id>
--message <message-id>`.
- `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
@@ -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 "<query>" --agent <agent-id> [--session <id>]
- `--kb` (chat) is required name-or-id. `--agent` (session ask) is required.
- `--session <id>` 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.
+6 -4
View File
@@ -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 '<expr>'` 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 <n> --host <url> --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 <name-or-id>`, set `WEKNORA_KB_ID`, or `weknora link` the dir |