WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

cli/internal/output/batch.go

@@ -0,0 +1,58 @@
+package output
+
+import "io"
+
+// BatchItem is one per-id outcome in a batch operation envelope.
+type BatchItem struct {
+	ID     string     `json:"id"`
+	OK     bool       `json:"ok"`
+	Result any        `json:"result,omitempty"`
+	Error  *ErrDetail `json:"error,omitempty"`
+}
+
+// WriteBatchEnvelope writes a batch operation envelope.
+//
+// Wire shape: {ok, data:[BatchItem...], meta:{count, successes, failures}, profile?}.
+// Top-level ok = (failures == 0). Per-id ok reflects each item's outcome.
+// Even when all items fail, the response stays in success-envelope shape
+// (data array, not error envelope) so agents can iterate detail per id.
+// profile is the resolved profile name for the invocation; empty string omits the field.
+func WriteBatchEnvelope(w io.Writer, items []BatchItem, indent bool, profile string) error {
+	if items == nil {
+		items = []BatchItem{}
+	}
+	successes, failures := 0, 0
+	for _, it := range items {
+		if it.OK {
+			successes++
+		} else {
+			failures++
+		}
+	}
+	env := Envelope{
+		OK:     failures == 0,
+		Status: batchStatus(successes, failures),
+		Data:   items,
+		Meta: &Meta{
+			Count:     IntPtr(len(items)),
+			Successes: &successes,
+			Failures:  &failures,
+		},
+		Profile: profile,
+	}
+	return writeJSON(w, env, indent)
+}
+
+// batchStatus maps the (successes, failures) counts to the tri-state envelope
+// status: "success" when no failures, "error" when no successes, "partial"
+// when both occur.
+func batchStatus(successes, failures int) string {
+	switch {
+	case failures == 0:
+		return "success"
+	case successes == 0:
+		return "error"
+	default:
+		return "partial"
+	}
+}

cli/internal/output/batch_test.go

@@ -0,0 +1,152 @@
+package output_test
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/Tencent/WeKnora/cli/internal/output"
+)
+
+func TestWriteBatchEnvelope_AllSuccess(t *testing.T) {
+	items := []output.BatchItem{
+		{ID: "id1", OK: true, Result: map[string]string{"deleted_at": "2026-05-20T00:00:00Z"}},
+		{ID: "id2", OK: true, Result: map[string]string{"deleted_at": "2026-05-20T00:00:00Z"}},
+	}
+	var buf bytes.Buffer
+	if err := output.WriteBatchEnvelope(&buf, items, false, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, `"ok":true`) {
+		t.Errorf("expected ok:true; got %q", got)
+	}
+	if !strings.Contains(got, `"successes":2`) {
+		t.Errorf("expected successes:2; got %q", got)
+	}
+	if !strings.Contains(got, `"count":2`) {
+		t.Errorf("expected count:2; got %q", got)
+	}
+}
+
+func TestWriteBatchEnvelope_PartialFailure(t *testing.T) {
+	items := []output.BatchItem{
+		{ID: "id1", OK: true, Result: map[string]string{"deleted_at": "2026-05-20T00:00:00Z"}},
+		{ID: "id2", OK: false, Error: &output.ErrDetail{Type: "resource.not_found", Message: "id2 not found"}},
+	}
+	var buf bytes.Buffer
+	if err := output.WriteBatchEnvelope(&buf, items, false, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, `"ok":false`) {
+		t.Errorf("expected ok:false (partial failure); got %q", got)
+	}
+	if !strings.Contains(got, `"successes":1`) || !strings.Contains(got, `"failures":1`) {
+		t.Errorf("expected counts; got %q", got)
+	}
+	if !strings.Contains(got, `"type":"resource.not_found"`) {
+		t.Errorf("expected per-item error; got %q", got)
+	}
+}
+
+func TestWriteBatchEnvelope_EmptyItems_EmitsEmptyArray(t *testing.T) {
+	var buf bytes.Buffer
+	if err := output.WriteBatchEnvelope(&buf, nil, false, ""); err != nil {
+		t.Fatalf("unexpected: %v", err)
+	}
+	got := buf.String()
+	if strings.Contains(got, `"data":null`) {
+		t.Errorf("empty items must marshal to [], not null; got %q", got)
+	}
+	if !strings.Contains(got, `"data":[]`) {
+		t.Errorf("expected data:[]; got %q", got)
+	}
+	if !strings.Contains(got, `"ok":true`) {
+		t.Errorf("expected ok:true for empty batch; got %q", got)
+	}
+	// count:0 is omitted by omitempty; assert no non-zero count appears.
+	if strings.Contains(got, `"count":`) {
+		// If count key is present, it must not be a non-zero value.
+		if !strings.Contains(got, `"count":0`) {
+			t.Errorf("count key present but not zero; got %q", got)
+		}
+	}
+}
+
+// TestWriteBatchEnvelope_StatusTriState verifies the additive tri-state
+// envelope.status: "success" (all ok), "partial" (mixed), "error" (all fail).
+func TestWriteBatchEnvelope_StatusTriState(t *testing.T) {
+	cases := []struct {
+		name   string
+		items  []output.BatchItem
+		status string
+	}{
+		{
+			name: "all_success",
+			items: []output.BatchItem{
+				{ID: "a", OK: true}, {ID: "b", OK: true},
+			},
+			status: "success",
+		},
+		{
+			name: "partial",
+			items: []output.BatchItem{
+				{ID: "a", OK: true},
+				{ID: "b", OK: false, Error: &output.ErrDetail{Type: "resource.not_found", Message: "missing"}},
+			},
+			status: "partial",
+		},
+		{
+			name: "all_fail",
+			items: []output.BatchItem{
+				{ID: "a", OK: false, Error: &output.ErrDetail{Type: "auth.forbidden", Message: "no perm"}},
+				{ID: "b", OK: false, Error: &output.ErrDetail{Type: "resource.not_found", Message: "missing"}},
+			},
+			status: "error",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			if err := output.WriteBatchEnvelope(&buf, tc.items, false, ""); err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			got := buf.String()
+			want := `"status":"` + tc.status + `"`
+			if !strings.Contains(got, want) {
+				t.Errorf("expected %s; got %q", want, got)
+			}
+		})
+	}
+}
+
+func TestWriteBatchEnvelope_AllFail(t *testing.T) {
+	items := []output.BatchItem{
+		{ID: "id1", OK: false, Error: &output.ErrDetail{Type: "auth.forbidden", Message: "no perm"}},
+		{ID: "id2", OK: false, Error: &output.ErrDetail{Type: "resource.not_found", Message: "missing"}},
+	}
+	var buf bytes.Buffer
+	if err := output.WriteBatchEnvelope(&buf, items, false, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, `"ok":false`) {
+		t.Errorf("expected ok:false; got %q", got)
+	}
+	// All-fail still uses the batch envelope shape; it does not degrade
+	// to ErrorEnvelope.
+	// An ErrorEnvelope has a top-level "error" key alongside "ok"; a batch
+	// envelope has a top-level "data" array. Check that "data":[  is present.
+	if !strings.Contains(got, `"data":[`) {
+		t.Errorf("batch all-fail should still use batch shape (data array), not error envelope; got %q", got)
+	}
+	if !strings.Contains(got, `"failures":2`) {
+		t.Errorf("expected failures:2; got %q", got)
+	}
+	// H3b invariant: successes:0 must appear even when all items failed.
+	// (*int semantics: nil is omitted; &0 is serialized as 0.)
+	if !strings.Contains(got, `"successes":0`) {
+		t.Errorf("all-fail batch must emit successes:0 (not omit it); invariant successes+failures==count would be broken; got %q", got)
+	}
+}

cli/internal/output/envelope.go

@@ -0,0 +1,135 @@
+// Package output defines the symmetric envelope wire contract:
+// success envelopes on stdout (Envelope) and error envelopes on
+// stderr (ErrorEnvelope), plus NDJSON stream helpers.
+package output
+
+import (
+	"encoding/json"
+	"io"
+)
+
+// Envelope is the success-path stdout envelope. See AGENTS.md
+// "Stdout (success path)" for the full wire contract.
+type Envelope struct {
+	OK bool `json:"ok"`
+	// Status is the batch tri-state outcome: "success" (all items ok),
+	// "partial" (some ok, some failed), or "error" (all failed). Set only by
+	// batch commands; omitted on ordinary single-result envelopes. `ok` stays
+	// authoritative — Status is an additive convenience for agents triaging
+	// multi-target results.
+	Status  string `json:"status,omitempty"`
+	Data    any    `json:"data,omitempty"`
+	Meta    *Meta  `json:"meta,omitempty"`
+	Profile string `json:"profile,omitempty"`
+}
+
+// ErrorEnvelope is the error-path stderr envelope. See AGENTS.md
+// "Stderr (error path)" for the full wire contract.
+type ErrorEnvelope struct {
+	OK    bool       `json:"ok"`
+	Error *ErrDetail `json:"error"`
+}
+
+// Meta carries optional metadata in success envelopes.
+type Meta struct {
+	// Count and TotalCount are *int so zero is serialized when explicitly set
+	// by list commands (omitempty on *int omits only nil, not zero). This keeps
+	// the agent contract stable: an empty list still emits count/total_count as 0
+	// instead of dropping the key. Non-list / dry-run metas leave them nil so they
+	// are omitted. Mirrors the Successes/Failures pointer pattern below.
+	Count      *int `json:"count,omitempty"`
+	HasMore    bool `json:"has_more,omitempty"`
+	TotalCount *int `json:"total_count,omitempty"`
+	// Successes and Failures are *int so zero is serialized when explicitly set
+	// by the batch path (omitempty on *int omits only nil, not zero).
+	// Non-batch commands leave these nil so they are omitted from the envelope.
+	Successes *int `json:"successes,omitempty"` // batch ops
+	Failures  *int `json:"failures,omitempty"`  // batch ops
+	// Hint is an optional actionable note on a SUCCESS envelope — e.g. an
+	// empty search explaining the KB may be unindexed, or a freshly-created
+	// draft document pointing at `doc reparse`. Distinct from error.hint;
+	// omitted when empty so it never adds noise to normal results.
+	Hint string `json:"hint,omitempty"`
+	// Dry-run preview fields. Populated by EmitDryRun (cmdutil/dryrun.go)
+	// when --dry-run is set on a mutation command; omitted otherwise.
+	DryRun bool           `json:"dry_run,omitempty"` // true when --dry-run; omitted otherwise
+	Plan   map[string]any `json:"plan,omitempty"`    // would-call shape; open map (action required, other fields command-specific)
+}
+
+// ErrDetail describes a structured error. Embedded in ErrorEnvelope.Error
+// and also surfaced in batch envelope per-item failures.
+type ErrDetail struct {
+	Type    string `json:"type"`
+	Message string `json:"message"`
+	// ExitCode is the process exit code this error maps to, embedded so an
+	// agent can branch on a single JSON read without observing $?. Needed
+	// because one type (input.invalid_argument) spans exit 2 (parse) and
+	// exit 5 (typed value) — exit_code disambiguates them.
+	ExitCode int    `json:"exit_code,omitempty"`
+	Hint     string `json:"hint,omitempty"`
+	// RetryArgv is a directly-executable argv array (e.g.
+	// ["weknora","auth","login"]) so an agent can exec it without
+	// shell-splitting or quote-handling. Distinct from the prose Hint.
+	RetryArgv         []string `json:"retry_argv,omitempty"`
+	RetryAfterSeconds int      `json:"retry_after_seconds,omitempty"`
+	// Retryable indicates whether re-running the SAME command may succeed:
+	// true for transient failures (timeouts, rate limits, transport), false
+	// for deterministic ones (auth, bad input, not-found), omitted (nil) when
+	// genuinely unknown.
+	Retryable *bool       `json:"retryable,omitempty"`
+	Risk      *RiskDetail `json:"risk,omitempty"`
+	Detail    any         `json:"detail,omitempty"`
+}
+
+// RiskDetail tags high-risk writes for the agent protocol. Surfaces in
+// error.risk on confirmation_required errors.
+// Level: "write" (reversible mutations — update) or "destructive" (delete);
+// the "read" slot is reserved.
+type RiskDetail struct {
+	Level  string `json:"level"`
+	Action string `json:"action"`
+}
+
+// NewEnvelope assembles a success Envelope with the given data + optional
+// meta + profile. Single source of construction so callers that need the
+// envelope value (e.g. jq filtering) stay in sync with WriteEnvelope when
+// fields are added.
+func NewEnvelope(data any, meta *Meta, profile string) Envelope {
+	return Envelope{
+		OK:      true,
+		Data:    data,
+		Meta:    meta,
+		Profile: profile,
+	}
+}
+
+// WriteEnvelope writes a success envelope to w. Caller sets data + optional meta.
+//
+// When profile is non-empty, the envelope includes a "profile" field.
+// indent: if true, output is multi-line (TTY mode); else compact (pipe mode).
+func WriteEnvelope(w io.Writer, data any, meta *Meta, indent bool, profile string) error {
+	return writeJSON(w, NewEnvelope(data, meta, profile), indent)
+}
+
+// WriteErrorEnvelope writes an error envelope to w (typically stderr).
+func WriteErrorEnvelope(w io.Writer, err *ErrDetail, indent bool) error {
+	env := ErrorEnvelope{
+		OK:    false,
+		Error: err,
+	}
+	return writeJSON(w, env, indent)
+}
+
+// IntPtr returns a pointer to i. Used by list commands to set Meta.Count /
+// Meta.TotalCount so that a zero count still serializes (omitempty on *int
+// omits only nil). Mirrors the Successes/Failures pointer pattern.
+func IntPtr(i int) *int { return &i }
+
+func writeJSON(w io.Writer, v any, indent bool) error {
+	enc := json.NewEncoder(w)
+	enc.SetEscapeHTML(false)
+	if indent {
+		enc.SetIndent("", "  ")
+	}
+	return enc.Encode(v)
+}

cli/internal/output/envelope_test.go

@@ -0,0 +1,116 @@
+package output_test
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/Tencent/WeKnora/cli/internal/output"
+)
+
+func TestWriteEnvelope_SuccessWithData(t *testing.T) {
+	var buf bytes.Buffer
+	data := map[string]string{"id": "kb_x"}
+	if err := output.WriteEnvelope(&buf, data, nil, false, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, `"ok":true`) {
+		t.Errorf("missing ok:true; got %q", got)
+	}
+	if !strings.Contains(got, `"data":{"id":"kb_x"}`) {
+		t.Errorf("missing data; got %q", got)
+	}
+}
+
+func TestWriteEnvelope_OmitDataWhenNil(t *testing.T) {
+	// Mutation with no payload: the data field should be omitted (omitempty).
+	var buf bytes.Buffer
+	if err := output.WriteEnvelope(&buf, nil, nil, false, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := buf.String()
+	if strings.Contains(got, `"data"`) {
+		t.Errorf("data field should be omitted when nil; got %q", got)
+	}
+	if !strings.Contains(got, `"ok":true`) {
+		t.Errorf("missing ok:true; got %q", got)
+	}
+}
+
+func TestWriteEnvelope_WithMeta(t *testing.T) {
+	var buf bytes.Buffer
+	meta := &output.Meta{Count: output.IntPtr(2), HasMore: false}
+	if err := output.WriteEnvelope(&buf, []string{"a", "b"}, meta, false, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, `"meta":{"count":2}`) {
+		// has_more:false should be omitted by omitempty when false
+		t.Errorf("meta unexpected shape; got %q", got)
+	}
+}
+
+// TestWriteEnvelope_ZeroCountSerializes pins the *int fix: a list command that
+// sets Count to 0 (empty result) must still emit "count":0, while a meta that
+// leaves Count nil (non-list / dry-run) must omit the key entirely. This is the
+// agent-contract guarantee that omitempty on a plain int silently broke.
+func TestWriteEnvelope_ZeroCountSerializes(t *testing.T) {
+	var bufZero bytes.Buffer
+	zero := &output.Meta{Count: output.IntPtr(0)}
+	if err := output.WriteEnvelope(&bufZero, []string{}, zero, false, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotZero := bufZero.String(); !strings.Contains(gotZero, `"count":0`) {
+		t.Errorf("explicit zero count must serialize; got %q", gotZero)
+	}
+
+	var bufNil bytes.Buffer
+	if err := output.WriteEnvelope(&bufNil, []string{}, &output.Meta{}, false, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotNil := bufNil.String(); strings.Contains(gotNil, "count") {
+		t.Errorf("nil count must be omitted; got %q", gotNil)
+	}
+}
+
+func TestWriteErrorEnvelope_FullShape(t *testing.T) {
+	var buf bytes.Buffer
+	errDetail := &output.ErrDetail{
+		Type:      "input.confirmation_required",
+		Message:   "kb delete kb_x requires confirmation",
+		Hint:      "re-run with -y/--yes",
+		RetryArgv: []string{"weknora", "kb", "delete", "kb_x", "-y"},
+		Risk: &output.RiskDetail{
+			Level:  "destructive",
+			Action: "kb.delete",
+		},
+	}
+	if err := output.WriteErrorEnvelope(&buf, errDetail, false); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, `"ok":false`) {
+		t.Errorf("missing ok:false; got %q", got)
+	}
+	if !strings.Contains(got, `"type":"input.confirmation_required"`) {
+		t.Errorf("missing typed code; got %q", got)
+	}
+	if !strings.Contains(got, `"retry_argv":["weknora","kb","delete","kb_x","-y"]`) {
+		t.Errorf("missing retry_argv; got %q", got)
+	}
+	if !strings.Contains(got, `"risk":{"level":"destructive","action":"kb.delete"}`) {
+		t.Errorf("missing risk; got %q", got)
+	}
+}
+
+func TestWriteEnvelope_IndentedTTYMode(t *testing.T) {
+	var buf bytes.Buffer
+	if err := output.WriteEnvelope(&buf, map[string]string{"id": "x"}, nil, true, ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, "\n  \"") {
+		t.Errorf("expected indented multi-line output; got %q", got)
+	}
+}

cli/internal/output/ndjson_stream.go

@@ -0,0 +1,49 @@
+package output
+
+import (
+	"encoding/json"
+	"io"
+)
+
+// InitEvent is the CLI-injected lifecycle event written at the head of a
+// streaming command's NDJSON output. Carries enough context for an agent to
+// thread follow-ups (session id, kb id, model, profile).
+//
+// Type field is always "init"; the JSON tag fixes the wire shape.
+type InitEvent struct {
+	Type      string `json:"type"`
+	SessionID string `json:"session_id"`
+	// MessageID anchors a resumed stream (`session resume`) 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"`
+	Model     string `json:"model,omitempty"`
+	Profile   string `json:"profile,omitempty"`
+}
+
+// WriteNDJSONLine emits one NDJSON event line to w.
+func WriteNDJSONLine(w io.Writer, v any) error {
+	enc := json.NewEncoder(w)
+	enc.SetEscapeHTML(false)
+	return enc.Encode(v)
+}
+
+// EmitInit writes the lifecycle init event to start an NDJSON stream.
+// MUST be called before any other writes to w within an NDJSON stream —
+// agents key on lines[0].type == "init" to discover session/profile/kb
+// context. Sets Type=init regardless of caller-supplied value.
+func EmitInit(w io.Writer, ev InitEvent) error {
+	ev.Type = "init"
+	return WriteNDJSONLine(w, ev)
+}
+
+// EmitSDKEvent passes through the raw SDK event as one NDJSON line.
+// The SDK is the source of truth for event vocabulary; the CLI does not
+// rename or reshape events.
+func EmitSDKEvent(w io.Writer, ev any) error {
+	return WriteNDJSONLine(w, ev)
+}

cli/internal/output/ndjson_stream_test.go

@@ -0,0 +1,74 @@
+package output_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/Tencent/WeKnora/cli/internal/output"
+)
+
+func TestEmitInit_ForcesTypeField(t *testing.T) {
+	var buf bytes.Buffer
+	// Pass an InitEvent with Type deliberately set to something wrong; EmitInit
+	// must overwrite it with "init".
+	ev := output.InitEvent{Type: "wrong", SessionID: "sess_x"}
+	if err := output.EmitInit(&buf, ev); err != nil {
+		t.Fatalf("EmitInit: %v", err)
+	}
+	var got struct {
+		Type      string `json:"type"`
+		SessionID string `json:"session_id"`
+	}
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+		t.Fatalf("unmarshal: %v\n%s", err, buf.String())
+	}
+	if got.Type != "init" {
+		t.Errorf("type: got %q, want init", got.Type)
+	}
+	if got.SessionID != "sess_x" {
+		t.Errorf("session_id: got %q, want sess_x", got.SessionID)
+	}
+}
+
+func TestEmitInit_OmitsEmptyOptionalFields(t *testing.T) {
+	var buf bytes.Buffer
+	// Only SessionID set; all optional fields should be absent from JSON.
+	ev := output.InitEvent{SessionID: "sess_only"}
+	if err := output.EmitInit(&buf, ev); err != nil {
+		t.Fatalf("EmitInit: %v", err)
+	}
+	line := buf.String()
+	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)
+		}
+	}
+}
+
+func TestEmitSDKEvent_PassthroughVerbatim(t *testing.T) {
+	var buf bytes.Buffer
+	payload := map[string]any{"type": "answer", "content": "hi"}
+	if err := output.EmitSDKEvent(&buf, payload); err != nil {
+		t.Fatalf("EmitSDKEvent: %v", err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+		t.Fatalf("unmarshal: %v\n%s", err, buf.String())
+	}
+	if got["type"] != "answer" {
+		t.Errorf("type: got %v, want answer", got["type"])
+	}
+	if got["content"] != "hi" {
+		t.Errorf("content: got %v, want hi", got["content"])
+	}
+	// Must be a single NDJSON line terminated by newline.
+	raw := buf.String()
+	if !strings.HasSuffix(raw, "\n") {
+		t.Errorf("NDJSON line must end with newline, got %q", raw)
+	}
+	if strings.Count(raw, "\n") != 1 {
+		t.Errorf("expected exactly one newline, got %d in %q", strings.Count(raw, "\n"), raw)
+	}
+}