feat(cli): session continue-stream + NDJSON init MessageID

Adds `weknora session continue-stream <session-id> --message <id>` for
re-attaching to an in-progress or already-completed SSE event buffer.

Server semantics (replay-from-0 + tail):
  - Every connection replays the full stored event log from index 0,
    then tails any new events. 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 surfaces local.sse_stream_aborted.

Output is NDJSON: one CLI-injected init line carrying
{session_id, message_id, profile} at stream head, then raw SDK
StreamResponse events verbatim. The init line lets agents thread the
resume to the original message in their dedupe table before the first
SDK frame arrives — output.InitEvent gains an omitempty MessageID field
for this purpose; non-resume init events stay unchanged.

The command always emits NDJSON regardless of --format — there is no
human-text use case for raw event-log replay (operator scenarios are
incident response / debugging). --dry-run is excluded for the same
reason streaming commands always are: a buffered plan makes no sense
for an event stream.
This commit is contained in:
nullkey
2026-05-28 04:28:59 +08:00
committed by lyingbug
parent 6d8c8650cd
commit 1bae6b6b6c
5 changed files with 392 additions and 1 deletions
+184
View File
@@ -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 <session-id> --message <id>`.
func NewCmdContinueStream(f *cmdutil.Factory) *cobra.Command {
opts := &ContinueStreamOptions{}
cmd := &cobra.Command{
Use: "continue-stream <session-id>",
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)
+201
View File
@@ -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 <session-id>.
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 <session-id> 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)
}
+1
View File
@@ -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
}
+5
View File
@@ -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"`
+1 -1
View File
@@ -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)
}