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