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:
@@ -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)
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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"`
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user