refactor(cli): resource-command refactors — --kb resolver, MCP session_ask, session stop (BREAKING)

Unify the --kb resolver (accepts name or UUID) across kb/doc/chunk/session/
search/chat/link; `agent create` attaches knowledge bases via --attach-kb
(no longer --kb). Rename the MCP tool agent_invoke → session_ask and drop dead
MCP error codes. Add `session stop` (StopSession), completing the
start / continue-stream / stop triad.

Across these commands, bring the agent contract up to par: --dry-run previews
on mutations (incl. kb pin/unpin, session stop), agent-help blobs on the
read/health surface, accurate destructive-confirmation verbs, and search
has_more truncation signalling so an agent can tell its results were capped.
This commit is contained in:
nullkey
2026-05-29 20:06:30 +08:00
committed by lyingbug
parent a68cc59310
commit c90f4e895e
54 changed files with 807 additions and 93 deletions
+1 -1
View File
@@ -7,7 +7,7 @@
// - Tool surface is hand-curated rather than auto-derived from the cobra
// tree (which would expose auth/link/completion/destructive verbs that
// don't belong on an agent-callable surface).
// - Long-running tools (chat / agent_invoke) accumulate the LLM SSE
// - Long-running tools (chat / session_ask) accumulate the LLM SSE
// stream server-side and return a single CallToolResult - MCP spec
// 2025-06-18 does not define streamed tool-result content, so the
// accumulate-and-return pattern is the canonical path.
+15 -15
View File
@@ -95,12 +95,12 @@ type chunkListService interface {
ListKnowledgeChunks(ctx context.Context, knowledgeID string, page, pageSize int, chunkTypes ...string) ([]sdk.Chunk, int64, error)
}
// agentInvokeService composes the two SDK methods agent_invoke needs
// sessionAskService composes the two SDK methods session_ask needs
// (CreateSession for the auto-session path + AgentQAStreamWithRequest
// for the run itself). Declared here alongside the per-domain
// interfaces above so ServiceClient (server.go) - which embeds the
// four domain interfaces - also satisfies it.
type agentInvokeService interface {
type sessionAskService interface {
CreateSession(ctx context.Context, req *sdk.CreateSessionRequest) (*sdk.Session, error)
AgentQAStreamWithRequest(ctx context.Context, sessionID string, req *sdk.AgentQARequest, cb sdk.AgentEventCallback) error
}
@@ -126,7 +126,7 @@ func registerTools(server *mcpsdk.Server, svc ServiceClient) {
addSearchChunks(server, svc)
addChat(server, svc)
addAgentList(server, svc)
addAgentInvoke(server, svc)
addSessionAsk(server, svc)
addChunkList(server, svc)
}
@@ -380,7 +380,7 @@ func addSearchChunks(server *mcpsdk.Server, svc knowledgeService) {
// nilable map[string]any that violates the auto-generated
// type=object constraint when empty. Skipping derivation by using
// `any` keeps the structured JSON shape identical while bypassing
// the over-eager validator. Same pattern applied to chat / agent_invoke
// the over-eager validator. Same pattern applied to chat / session_ask
// below.
mcpsdk.AddTool(server, &mcpsdk.Tool{
Name: "search_chunks",
@@ -513,7 +513,7 @@ type agentListOutput struct {
func addAgentList(server *mcpsdk.Server, svc agentService) {
mcpsdk.AddTool(server, &mcpsdk.Tool{
Name: "agent_list",
Description: "List the tenant's custom agents. Returns items[] with id, name, description, is_builtin - use to discover an agent_id before agent_invoke.",
Description: "List the tenant's custom agents. Returns items[] with id, name, description, is_builtin - use to discover an agent_id before session_ask.",
Annotations: &mcpsdk.ToolAnnotations{
Title: "List Custom Agents",
DestructiveHint: bptr(false),
@@ -533,15 +533,15 @@ func addAgentList(server *mcpsdk.Server, svc agentService) {
})
}
// ---- agent_invoke --------------------------------------------------------
// ---- session_ask ---------------------------------------------------------
type agentInvokeInput struct {
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"`
}
type agentInvokeOutput struct {
type sessionAskOutput struct {
Answer string `json:"answer"`
References []*sdk.SearchResult `json:"references"`
ToolEvents []sse.AgentToolEvent `json:"tool_events,omitempty"`
@@ -551,18 +551,18 @@ type agentInvokeOutput struct {
Query string `json:"query"`
}
func addAgentInvoke(server *mcpsdk.Server, svc agentInvokeService) {
func addSessionAsk(server *mcpsdk.Server, svc sessionAskService) {
mcpsdk.AddTool(server, &mcpsdk.Tool{
Name: "agent_invoke",
Description: "Run a query through a custom 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.",
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.",
Annotations: &mcpsdk.ToolAnnotations{
Title: "Invoke Custom Agent",
Title: "Ask a Custom Agent (session ask --agent)",
DestructiveHint: bptr(false),
ReadOnlyHint: false,
IdempotentHint: false,
OpenWorldHint: bptr(true),
},
}, func(ctx context.Context, _ *mcpsdk.CallToolRequest, in agentInvokeInput) (*mcpsdk.CallToolResult, any, error) {
}, func(ctx context.Context, _ *mcpsdk.CallToolRequest, in sessionAskInput) (*mcpsdk.CallToolResult, any, error) {
if in.AgentID == "" {
return toolErrorResult(cmdutil.NewError(cmdutil.CodeInputMissingFlag, "agent_id is required")), nil, nil
}
@@ -580,7 +580,7 @@ func addAgentInvoke(server *mcpsdk.Server, svc agentInvokeService) {
// agnostic at creation (verified against server source).
sessionID := in.SessionID
if sessionID == "" {
sess, err := svc.CreateSession(ctx, &sdk.CreateSessionRequest{Title: "weknora mcp agent_invoke"})
sess, err := svc.CreateSession(ctx, &sdk.CreateSessionRequest{Title: "weknora mcp session_ask"})
if err != nil {
return toolErrorResult(cmdutil.WrapHTTP(err, "create chat session")), nil, nil
}
@@ -596,7 +596,7 @@ func addAgentInvoke(server *mcpsdk.Server, svc agentInvokeService) {
if !acc.Done() {
return toolErrorResult(cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")), nil, nil
}
return successResult(agentInvokeOutput{
return successResult(sessionAskOutput{
Answer: acc.Answer(),
References: acc.References,
ToolEvents: acc.ToolEvents,
+33 -10
View File
@@ -196,7 +196,7 @@ func TestTool_ListsRegistered(t *testing.T) {
if err != nil {
t.Fatalf("ListTools: %v", err)
}
want := []string{"kb_list", "kb_view", "doc_list", "doc_view", "doc_download", "search_chunks", "chat", "agent_list", "agent_invoke", "chunk_list"}
want := []string{"kb_list", "kb_view", "doc_list", "doc_view", "doc_download", "search_chunks", "chat", "agent_list", "session_ask", "chunk_list"}
got := map[string]bool{}
for _, tool := range res.Tools {
got[tool.Name] = true
@@ -211,6 +211,29 @@ func TestTool_ListsRegistered(t *testing.T) {
}
}
// TestTool_SessionAsk_NotAgentInvoke asserts the MCP rename landed: the
// registered set must contain "session_ask" and must NOT contain the
// stale "agent_invoke" name (clean break, no deprecation alias).
func TestTool_SessionAsk_NotAgentInvoke(t *testing.T) {
c, _ := newTestServer(t, &fakeSvc{})
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
res, err := c.ListTools(ctx, nil)
if err != nil {
t.Fatalf("ListTools: %v", err)
}
names := map[string]bool{}
for _, tool := range res.Tools {
names[tool.Name] = true
}
if !names["session_ask"] {
t.Error("expected tool 'session_ask' to be registered")
}
if names["agent_invoke"] {
t.Error("stale tool 'agent_invoke' must NOT be registered (clean break, no alias)")
}
}
func TestTool_KBList(t *testing.T) {
svc := &fakeSvc{listKBs: []sdk.KnowledgeBase{{ID: "kb1", Name: "Marketing"}}}
c, _ := newTestServer(t, svc)
@@ -448,7 +471,7 @@ func TestMCP_ChatToolReturnsThinking(t *testing.T) {
}
}
func TestMCP_AgentInvokeToolReturnsToolCalls(t *testing.T) {
func TestMCP_SessionAskToolReturnsToolCalls(t *testing.T) {
svc := &fakeSvc{
agentEvents: []*sdk.AgentStreamResponse{
{ResponseType: sdk.AgentResponseTypeThinking, Content: "agent thinks"},
@@ -458,8 +481,8 @@ func TestMCP_AgentInvokeToolReturnsToolCalls(t *testing.T) {
},
}
c, _ := newTestServer(t, svc)
var out agentInvokeOutput
callTool(t, c, "agent_invoke", map[string]any{"agent_id": "ag1", "query": "tool question"}, &out)
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")
}
@@ -495,7 +518,7 @@ func TestTool_AgentList(t *testing.T) {
}
}
func TestTool_AgentInvoke(t *testing.T) {
func TestTool_SessionAsk(t *testing.T) {
svc := &fakeSvc{
agentEvents: []*sdk.AgentStreamResponse{
{ResponseType: sdk.AgentResponseTypeAnswer, Content: "result"},
@@ -504,8 +527,8 @@ func TestTool_AgentInvoke(t *testing.T) {
},
}
c, _ := newTestServer(t, svc)
var out agentInvokeOutput
callTool(t, c, "agent_invoke", map[string]any{"agent_id": "ag1", "query": "x"}, &out)
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)
}
@@ -517,7 +540,7 @@ func TestTool_AgentInvoke(t *testing.T) {
}
}
func TestTool_AgentInvoke_StreamAbort(t *testing.T) {
func TestTool_SessionAsk_StreamAbort(t *testing.T) {
svc := &fakeSvc{
agentEvents: []*sdk.AgentStreamResponse{{ResponseType: sdk.AgentResponseTypeAnswer, Content: "partial"}},
agentStreamErr: errors.New("connection reset"),
@@ -525,7 +548,7 @@ func TestTool_AgentInvoke_StreamAbort(t *testing.T) {
c, _ := newTestServer(t, svc)
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
res, err := c.CallTool(ctx, &mcpsdk.CallToolParams{Name: "agent_invoke", Arguments: map[string]any{"agent_id": "ag1", "query": "x"}})
res, err := c.CallTool(ctx, &mcpsdk.CallToolParams{Name: "session_ask", Arguments: map[string]any{"agent_id": "ag1", "query": "x"}})
if err != nil {
t.Fatalf("unexpected transport error: %v", err)
}
@@ -625,7 +648,7 @@ func TestToolAnnotations_AllToolsHaveExpectedHints(t *testing.T) {
"search_chunks": {destructive: false, readOnly: true, idempotent: true, openWorld: false, title: "Search Knowledge Chunks"},
"chat": {destructive: false, readOnly: false, idempotent: false, openWorld: true, title: "Chat with KB (Streaming RAG)"},
"agent_list": {destructive: false, readOnly: true, idempotent: true, openWorld: false, title: "List Custom Agents"},
"agent_invoke": {destructive: false, readOnly: false, idempotent: false, openWorld: true, title: "Invoke Custom Agent"},
"session_ask": {destructive: false, readOnly: false, idempotent: false, openWorld: true, title: "Ask a Custom Agent (session ask --agent)"},
"chunk_list": {destructive: false, readOnly: true, idempotent: true, openWorld: false, title: "List Knowledge Chunks"},
}