diff --git a/cli/cmd/session/continue_stream.go b/cli/cmd/session/continue_stream.go new file mode 100644 index 00000000..704ffc7d --- /dev/null +++ b/cli/cmd/session/continue_stream.go @@ -0,0 +1,184 @@ +// continue_stream.go implements `weknora session continue-stream` — +// re-attach to an SSE event buffer for an in-progress or already-completed +// assistant message under a known session_id. +// +// Server semantics: +// - Replay-from-0 + tail: every connection replays the entire stored event +// log from index 0, then tails any new events. NOT a cursor-from-disconnect +// model. Agents that already consumed events on the original stream MUST +// dedupe (by message_id + event hash, or by AssistantMessageID + content +// fingerprint) to avoid double-processing. +// - Buffer TTL: +// redis mode - 1h hardcoded (not configurable from the CLI) +// memory mode - process lifetime (server restart = data loss) +// After TTL the server returns an error which the CLI maps to +// local.sse_stream_aborted. +// +// Output shape matches `weknora chat` and `weknora session ask` NDJSON mode: +// one CLI-injected init line carrying {session_id, message_id, profile} at +// stream head, then SDK StreamResponse events verbatim. The init line lets +// agents thread the resume to the original message in their dedupe table +// without parsing the first SDK event. +package sessioncmd + +import ( + "context" + + "github.com/spf13/cobra" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/output" + sdk "github.com/Tencent/WeKnora/client" +) + +// continueStreamFields enumerates the NDJSON init-event + raw SDK event +// vocabulary surfaced for `--format json` / `--format ndjson` discovery. +var continueStreamFields = []string{ + "session_id", "message_id", + // SDK StreamResponse fields (pass-through): id, response_type, content, + // done, knowledge_references, assistant_message_id, session_id, + // tool_calls, data +} + +// ContinueStreamOptions captures `session continue-stream` flag/arg state. +type ContinueStreamOptions struct { + SessionID string + MessageID string +} + +// ContinueStreamService is the narrow SDK surface this command depends on. +// *sdk.Client satisfies it; tests substitute a fake. Compile-time check +// at the bottom of this file. +type ContinueStreamService interface { + ContinueStream(ctx context.Context, sessionID, messageID string, cb func(*sdk.StreamResponse) error) error +} + +// NewCmdContinueStream builds `weknora session continue-stream --message `. +func NewCmdContinueStream(f *cmdutil.Factory) *cobra.Command { + opts := &ContinueStreamOptions{} + cmd := &cobra.Command{ + Use: "continue-stream ", + Short: "Resume an SSE event stream for an in-progress or completed session message", + Long: `Re-attach to the SSE event buffer for an assistant message under a known session. + +The server replays the entire stored event log for the given (session_id, message_id) +from index 0, then tails any new events. This is NOT a cursor-from-disconnect +model: agents that already consumed events on the original stream MUST dedupe +(by message_id or event content hash) to avoid double-processing. + +Buffer TTL: + - redis mode: 1h hardcoded (not configurable from the CLI) + - memory mode: process lifetime (server restart = data loss) + +After TTL expiry the CLI surfaces local.sse_stream_aborted. + +Typical use cases: + - Network blip mid-stream: re-attach with the same session_id + message_id + from the original 'session ask' / 'chat' init event. + - Long-running agent invocation: poll progress without blocking the original + stream. + - Post-mortem inspection: replay the full event history of a completed + message for debugging. + +Output is NDJSON (matches 'chat' / 'session ask' --format json|ndjson): +one init line at head ({session_id, message_id, profile}), then raw SDK +StreamResponse events verbatim. + +Note: unlike 'chat' / 'session ask', this command always emits NDJSON +regardless of --format value. The operator use case (incident response, +debugging) always wants the raw event log; there is no human-text rendering. +--format json and --format ndjson behave identically here; --format text is +silently treated as NDJSON.`, + Example: ` weknora session continue-stream sess_xyz --message msg_abc + weknora session continue-stream sess_xyz -m msg_abc --format ndjson`, + Args: cobra.ExactArgs(1), + RunE: func(c *cobra.Command, args []string) error { + opts.SessionID = args[0] + fopts, err := cmdutil.CheckFormatFlag(c) + if err != nil { + return err + } + fopts.ResolveDefault(iostreams.IO.IsStdoutTTY()) + cli, err := f.Client() + if err != nil { + return err + } + return runContinueStream(c.Context(), opts, fopts, cli) + }, + } + cmd.Flags().StringVarP(&opts.MessageID, "message", "m", "", + "Assistant message ID to resume (from the init or agent_query event of the original stream)") + _ = cmd.MarkFlagRequired("message") + cmdutil.AddFormatFlag(cmd, continueStreamFields...) + cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{ + UsedFor: "Resume an SSE event stream for an in-progress or completed assistant message. Produces an NDJSON event stream: init line (session_id, message_id) then raw SDK StreamResponse events.", + RequiredFlags: []string{"--message (message_id from prior init / agent_query event)"}, + Examples: []string{ + "weknora session continue-stream sess_xyz --message msg_abc --format json", + "# Network-blip recovery: replay with same session_id + message_id from the original 'session ask' init event", + }, + Output: "NDJSON stream: {type:init, session_id, message_id, profile} then SDK StreamResponse events (response_type, content, done, knowledge_references, assistant_message_id, ...)", + Warnings: []string{ + "Server replays from event 0 (NOT cursor-from-disconnect). Agents that already consumed events on the original stream MUST dedupe by message_id + event hash to avoid double-processing.", + "Buffer TTL: redis mode 1h hardcoded; memory mode = process lifetime. After expiry the CLI returns local.sse_stream_aborted.", + }, + }) + return cmd +} + +// runContinueStream is the testable core: validate, dispatch the resume, and +// route the NDJSON stream. Returns a typed error. +// +// Always emits NDJSON: a buffered envelope makes no sense for a streaming +// command, and continue-stream has no human-text use case (operators reach +// for it during incident response / debugging, which always wants the raw +// event log). --format text is therefore treated identically to --format +// json/ndjson here. +func runContinueStream(ctx context.Context, opts *ContinueStreamOptions, _ *cmdutil.FormatOptions, svc ContinueStreamService) error { + if opts.SessionID == "" { + return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "session-id argument cannot be empty") + } + if opts.MessageID == "" { + return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--message cannot be empty") + } + if svc == nil { + return cmdutil.NewError(cmdutil.CodeServerError, "session continue-stream: no SDK client available") + } + + w := iostreams.IO.Out + + // 1. Inject the CLI-managed init event at stream head. Both session_id + // and message_id are populated so agents can key their dedupe table + // on the resumed message before the first SDK frame arrives. + initEv := output.InitEvent{ + SessionID: opts.SessionID, + MessageID: opts.MessageID, + Profile: cmdutil.GetProfile(), + } + if err := output.EmitInit(w, initEv); err != nil { + return err + } + + // 2. Open the SDK replay stream and pass each event through as a bare + // NDJSON line. The SDK's StreamResponse is the source of truth for + // the event vocabulary; the CLI does not reshape it. + cb := func(r *sdk.StreamResponse) error { + return output.EmitSDKEvent(w, r) + } + if err := svc.ContinueStream(ctx, opts.SessionID, opts.MessageID, cb); err != nil { + // Ctrl-C / SIGTERM lineage (operator gave up on the resume). + if cmdutil.IsCancelled(ctx, err) { + return cmdutil.Wrapf(cmdutil.CodeOperationCancelled, err, "session continue-stream cancelled") + } + // Pre-stream HTTP / transport failure (e.g. 404 if message_id is + // unknown, or buffer-expired body from the server). Route through + // the canonical classifier so codes survive — 404 still surfaces + // as resource.not_found etc. + return cmdutil.WrapHTTP(err, "continue stream") + } + return nil +} + +// compile-time check: production SDK client satisfies ContinueStreamService. +var _ ContinueStreamService = (*sdk.Client)(nil) diff --git a/cli/cmd/session/continue_stream_test.go b/cli/cmd/session/continue_stream_test.go new file mode 100644 index 00000000..bbdc18df --- /dev/null +++ b/cli/cmd/session/continue_stream_test.go @@ -0,0 +1,201 @@ +package sessioncmd + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + sdk "github.com/Tencent/WeKnora/client" +) + +// scriptedContinueStreamSvc serves a canned stream of StreamResponse events +// to runContinueStream and records the (sessionID, messageID) passed in. +type scriptedContinueStreamSvc struct { + events []*sdk.StreamResponse + streamErr error + got struct { + sessionID string + messageID string + } +} + +func (s *scriptedContinueStreamSvc) ContinueStream(_ context.Context, sessionID, messageID string, cb func(*sdk.StreamResponse) error) error { + s.got.sessionID = sessionID + s.got.messageID = messageID + for _, e := range s.events { + if err := cb(e); err != nil { + return err + } + } + return s.streamErr +} + +func contStreamAnswer(content string) *sdk.StreamResponse { + return &sdk.StreamResponse{ResponseType: sdk.ResponseTypeAnswer, Content: content} +} +func contStreamComplete() *sdk.StreamResponse { + return &sdk.StreamResponse{ResponseType: sdk.ResponseTypeComplete, Done: true} +} + +// TestContinueStream_NDJSON_FirstLineIsInitWithMessageID verifies the +// CLI-injected init line carries both session_id and message_id, so agents +// can key dedupe tables on the resumed message before the first SDK frame +// arrives. +func TestContinueStream_NDJSON_FirstLineIsInitWithMessageID(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &scriptedContinueStreamSvc{ + events: []*sdk.StreamResponse{contStreamAnswer("hello"), contStreamComplete()}, + } + opts := &ContinueStreamOptions{SessionID: "sess_xyz", MessageID: "msg_abc"} + require.NoError(t, runContinueStream(context.Background(), opts, ndjsonOpts(), svc)) + + lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n") + require.GreaterOrEqual(t, len(lines), 1, "expected at least the init line") + + var first struct { + Type string `json:"type"` + SessionID string `json:"session_id"` + MessageID string `json:"message_id"` + } + require.NoError(t, json.Unmarshal([]byte(lines[0]), &first), "first line must be valid JSON: %q", lines[0]) + assert.Equal(t, "init", first.Type) + assert.Equal(t, "sess_xyz", first.SessionID) + assert.Equal(t, "msg_abc", first.MessageID, "init.message_id must echo --message (anchor for dedupe)") +} + +// TestContinueStream_NDJSON_PassthroughEvents verifies: 1 init line + N SDK +// events = N+1 total lines, all valid JSON. +func TestContinueStream_NDJSON_PassthroughEvents(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &scriptedContinueStreamSvc{ + events: []*sdk.StreamResponse{ + contStreamAnswer("alpha"), + contStreamAnswer("beta"), + contStreamComplete(), + }, + } + opts := &ContinueStreamOptions{SessionID: "sess_x", MessageID: "msg_y"} + require.NoError(t, runContinueStream(context.Background(), opts, ndjsonOpts(), svc)) + + lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n") + // 1 init + 3 SDK events = 4 lines. + require.Equal(t, 4, len(lines), "expected init + 3 SDK events:\n%s", out.String()) + for i, line := range lines { + var obj map[string]any + assert.NoError(t, json.Unmarshal([]byte(line), &obj), "line %d not valid JSON: %q", i+1, line) + } +} + +// TestContinueStream_PassesSessionAndMessageIDToSDK verifies the args + flag +// flow through to the SDK call. +func TestContinueStream_PassesSessionAndMessageIDToSDK(t *testing.T) { + _, _ = iostreams.SetForTest(t) + svc := &scriptedContinueStreamSvc{events: []*sdk.StreamResponse{contStreamComplete()}} + opts := &ContinueStreamOptions{SessionID: "sess_42", MessageID: "msg_99"} + require.NoError(t, runContinueStream(context.Background(), opts, ndjsonOpts(), svc)) + assert.Equal(t, "sess_42", svc.got.sessionID) + assert.Equal(t, "msg_99", svc.got.messageID) +} + +// TestContinueStream_EmptySessionID_Rejected guards the direct-test entry +// point (cobra blocks empty positional via ExactArgs(1), but the runtime +// core must also refuse empty strings). +func TestContinueStream_EmptySessionID_Rejected(t *testing.T) { + _, _ = iostreams.SetForTest(t) + svc := &scriptedContinueStreamSvc{} + opts := &ContinueStreamOptions{SessionID: "", MessageID: "msg_x"} + err := runContinueStream(context.Background(), opts, ndjsonOpts(), svc) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} + +// TestContinueStream_EmptyMessageID_Rejected guards the direct-test entry +// point. +func TestContinueStream_EmptyMessageID_Rejected(t *testing.T) { + _, _ = iostreams.SetForTest(t) + svc := &scriptedContinueStreamSvc{} + opts := &ContinueStreamOptions{SessionID: "sess_x", MessageID: ""} + err := runContinueStream(context.Background(), opts, ndjsonOpts(), svc) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) +} + +// TestContinueStream_Cancellation_MapsToOperationCancelled verifies a +// cancelled context maps to operation.cancelled (Ctrl-C lineage). +func TestContinueStream_Cancellation_MapsToOperationCancelled(t *testing.T) { + _, _ = iostreams.SetForTest(t) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + svc := &scriptedContinueStreamSvc{streamErr: context.Canceled} + opts := &ContinueStreamOptions{SessionID: "sess_x", MessageID: "msg_x"} + err := runContinueStream(ctx, opts, ndjsonOpts(), svc) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeOperationCancelled, typed.Code) +} + +// TestContinueStream_NotFound_MapsToResourceNotFound verifies an SDK 404 +// (e.g. unknown message_id, or buffer expired past TTL) is classified by +// the canonical HTTP classifier. +func TestContinueStream_NotFound_MapsToResourceNotFound(t *testing.T) { + _, _ = iostreams.SetForTest(t) + svc := &scriptedContinueStreamSvc{streamErr: errors.New("HTTP error 404: not found")} + opts := &ContinueStreamOptions{SessionID: "sess_x", MessageID: "msg_missing"} + err := runContinueStream(context.Background(), opts, ndjsonOpts(), svc) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeResourceNotFound, typed.Code) +} + +// TestContinueStream_RequiresMessageFlag verifies cobra refuses to run the +// command without --message (the flag is marked required). +func TestContinueStream_RequiresMessageFlag(t *testing.T) { + f := &cmdutil.Factory{} + cmd := NewCmdContinueStream(f) + var buf bytes.Buffer + cmd.SetOut(&buf) + cmd.SetErr(&buf) + cmd.SetArgs([]string{"sess_xyz"}) // positional only, no --message + err := cmd.Execute() + require.Error(t, err, "expected required-flag error when --message is missing") + assert.True(t, + strings.Contains(err.Error(), "message") || strings.Contains(err.Error(), "required"), + "error should mention the required --message flag: %v", err) + // Note: cobra's bare required-flag error here is not yet wrapped as + // FlagError - that mapping happens in cmd/root.go for top-level Execute. + // Asserting the message text is sufficient for this unit-level check; + // exit-code mapping is covered by cmd/root tests. +} + +// TestContinueStream_RequiresSessionIDArg verifies cobra refuses to run the +// command without the positional . +func TestContinueStream_RequiresSessionIDArg(t *testing.T) { + f := &cmdutil.Factory{} + cmd := NewCmdContinueStream(f) + var buf bytes.Buffer + cmd.SetOut(&buf) + cmd.SetErr(&buf) + cmd.SetArgs([]string{"--message", "msg_abc"}) // missing positional + err := cmd.Execute() + require.Error(t, err, "expected ExactArgs(1) error when is missing") + // Cobra reports "accepts 1 arg(s), received 0" — assert on substance, + // not exit-code mapping (the latter happens in cmd/root, see + // TestContinueStream_RequiresMessageFlag note). + assert.True(t, + strings.Contains(err.Error(), "arg") || strings.Contains(err.Error(), "received"), + "error should mention arg-count: %v", err) +} diff --git a/cli/cmd/session/session.go b/cli/cmd/session/session.go index 920bcef1..b968a239 100644 --- a/cli/cmd/session/session.go +++ b/cli/cmd/session/session.go @@ -22,5 +22,6 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command { cmd.AddCommand(NewCmdView(f)) cmd.AddCommand(NewCmdDelete(f)) cmd.AddCommand(NewCmdAsk(f)) + cmd.AddCommand(NewCmdContinueStream(f)) return cmd } diff --git a/cli/internal/output/ndjson_stream.go b/cli/internal/output/ndjson_stream.go index baff1dab..f0a4fafc 100644 --- a/cli/internal/output/ndjson_stream.go +++ b/cli/internal/output/ndjson_stream.go @@ -13,6 +13,11 @@ import ( type InitEvent struct { Type string `json:"type"` SessionID string `json:"session_id"` + // MessageID anchors a resumed stream (`session continue-stream`) to the + // specific assistant message whose event buffer is being replayed. Empty + // for fresh streams (chat / session ask) where the message id is only + // known after the SDK emits its first agent_query frame. + MessageID string `json:"message_id,omitempty"` AgentID string `json:"agent_id,omitempty"` KBID string `json:"kb_id,omitempty"` RequestID string `json:"request_id,omitempty"` diff --git a/cli/internal/output/ndjson_stream_test.go b/cli/internal/output/ndjson_stream_test.go index 8a05f20a..1d39095d 100644 --- a/cli/internal/output/ndjson_stream_test.go +++ b/cli/internal/output/ndjson_stream_test.go @@ -40,7 +40,7 @@ func TestEmitInit_OmitsEmptyOptionalFields(t *testing.T) { t.Fatalf("EmitInit: %v", err) } line := buf.String() - for _, field := range []string{"kb_id", "agent_id", "model", "profile", "request_id"} { + for _, field := range []string{"kb_id", "agent_id", "model", "profile", "request_id", "message_id"} { if strings.Contains(line, `"`+field+`"`) { t.Errorf("optional field %q should be omitted when empty, got: %s", field, line) }