diff --git a/.changeset/sta-445-mcp-prompts.md b/.changeset/sta-445-mcp-prompts.md new file mode 100644 index 00000000..ba8e466b --- /dev/null +++ b/.changeset/sta-445-mcp-prompts.md @@ -0,0 +1,5 @@ +--- +"@stainless-code/verdict": minor +--- + +MCP hosts can now load the Procedure straight from the binary. `prompts/list` and `prompts/get` serve five task prompts (`address-reviews`, `fix-ci`, `incremental-review`, `review`, `validate`), and `resources/list` and `resources/read` serve every payload file at `verdict://skill/`, byte-identical to `verdict skill show`. Prompts and resources are read-only and available in every server mode, including `--read-only` and `--operator`. `initialize` advertises both capabilities and points hosts at the `review` prompt or `verdict://skill/PROCEDURE.md`. diff --git a/docs/manual.md b/docs/manual.md index 8b4f2454..066d2267 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -1678,6 +1678,17 @@ context. A malformed call is a JSON-RPC `-32602` error, not a refusal. Human progress and warnings go to stderr (or MCP notifications), never stdout: stdout is the protocol channel. +`prompts/list` offers five task prompts (`address-reviews`, `fix-ci`, +`incremental-review`, `review`, `validate`). `prompts/get` takes the +prompt name and no arguments, and returns that task's Procedure assembled by +the binary from its embedded payload. `resources/list` serves every payload +file at `verdict://skill/` — +`resources/read` returns text byte-identical to `verdict skill show`. +Prompts and resources are read-only in every server mode, including +`--read-only` and `--operator`, and `skill` remains a distribution surface, +never a tool. `initialize` advertises both capabilities +and points hosts at the `review` prompt or `verdict://skill/PROCEDURE.md`. + #### Host config `verdict mcp config --agent ` diff --git a/internal/archtest/manual_surfaces_test.go b/internal/archtest/manual_surfaces_test.go index 765f992a..119606ca 100644 --- a/internal/archtest/manual_surfaces_test.go +++ b/internal/archtest/manual_surfaces_test.go @@ -74,6 +74,15 @@ var manualSurfaces = []manualSurface{ "bad-recipe", "unknown-recipe", "--stage ", "data.stage", }, }, + { + section: "MCP prompts and resources", + heading: "### MCP server (stdio, experimental until 1.0)", + terms: []string{ + "prompts/list", "prompts/get", "resources/list", "resources/read", + "verdict://skill/", "byte-identical to `verdict skill show`", + "every server mode", "verdict://skill/PROCEDURE.md", + }, + }, { section: "serve local HTTP surface", heading: "## Serve (local HTTP surface)", diff --git a/internal/mcp/contract_test.go b/internal/mcp/contract_test.go index 30a600b1..73ac0f52 100644 --- a/internal/mcp/contract_test.go +++ b/internal/mcp/contract_test.go @@ -122,6 +122,28 @@ func TestSurfaceSets(t *testing.T) { } } +// TestInitializeCapabilitiesSnapshot pins the three advertised surfaces. +func TestInitializeCapabilitiesSnapshot(t *testing.T) { + t.Parallel() + cfg := testConfig() + frames := serve(t, &cfg, + `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`) + var init initializeResult + if err := json.Unmarshal(frames["1"].Result, &init); err != nil { + t.Fatal(err) + } + raw, err := json.Marshal(init.Capabilities) + if err != nil { + t.Fatal(err) + } + const want = `{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}}` + if string(raw) != want { + t.Fatalf("capabilities = %s, want %s", raw, want) + } +} + +const procedureInstruction = "For the Procedure, use the review prompt or read verdict://skill/PROCEDURE.md." + // TestInitializeInstructions proves every client receives the short doctrine // block, and that the operator boundary matches the surface. // @@ -137,12 +159,12 @@ func TestInitializeInstructions(t *testing.T) { }{ { name: "agent", - want: []string{"fetch", "review.json", "post", "triage[]", "hint", "not on this surface"}, + want: []string{"fetch", "review.json", "post", "triage[]", "hint", "not on this surface", procedureInstruction}, }, { name: "operator", operator: true, - want: []string{"fetch", "post", "triage", "runs with --operator"}, + want: []string{"fetch", "post", "triage", "runs with --operator", procedureInstruction}, absent: []string{"not on this surface"}, }, } diff --git a/internal/mcp/modes_test.go b/internal/mcp/modes_test.go new file mode 100644 index 00000000..28451ddc --- /dev/null +++ b/internal/mcp/modes_test.go @@ -0,0 +1,175 @@ +package mcp + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "strconv" + "testing" + + skillfs "github.com/stainless-code/verdict" + "github.com/stainless-code/verdict/internal/core/skill" +) + +type procedureModeCase struct { + name string + tools int + readOnly bool + operator bool +} + +// TestProcedureSurfacesIgnoreModes proves prompts and resources are +// byte-for-byte the same on every tool surface. The tool counts pin that the +// three configs really are different surfaces. +func TestProcedureSurfacesIgnoreModes(t *testing.T) { + t.Parallel() + cases := []procedureModeCase{ + {name: "default", tools: 25}, + {name: "read-only", tools: 14, readOnly: true}, + {name: "operator", tools: 26, operator: true}, + } + paths, wantPrompt, wantResource := procedureFixtures(t) + + var baseline procedureWire + for i, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + cfg := testConfig() + cfg.ReadOnly = tc.readOnly + cfg.Operator = tc.operator + frames := procedureFrames(t, &cfg) + checkProcedureSurface(t, tc, frames, len(paths), len(skillfs.Tasks()), wantPrompt, wantResource) + wire := procedureWireFrom(frames) + if i == 0 { + baseline = wire + return + } + checkProcedureWire(t, tc.name, &wire, &baseline) + }) + } +} + +func procedureFixtures(t *testing.T) ([]string, []byte, []byte) { + t.Helper() + paths, err := skillfs.Paths() + if err != nil { + t.Fatal(err) + } + wantResource, ref := skill.ShowFile(context.Background(), &skill.Request{}, "PROCEDURE.md") + if ref != nil { + t.Fatal(ref) + } + wantPrompt, err := skillfs.ReviewProcedure() + if err != nil { + t.Fatal(err) + } + return paths, wantPrompt, wantResource +} + +func procedureFrames(t *testing.T, cfg *Config) map[string]frame { + t.Helper() + lines := []string{ + `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`, + `{"jsonrpc":"2.0","id":2,"method":"prompts/list"}`, + `{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"review"}}`, + `{"jsonrpc":"2.0","id":4,"method":"resources/list"}`, + fmt.Sprintf(`{"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":%q}}`, + resourceURIPrefix+"PROCEDURE.md"), + } + frames := serve(t, cfg, lines...) + for i := range lines { + id := strconv.Itoa(i + 1) + if frame := frames[id]; frame.Error != nil { + t.Fatalf("request %s error = %+v", id, frame.Error) + } + } + return frames +} + +func checkProcedureSurface(t *testing.T, tc procedureModeCase, frames map[string]frame, + pathCount, taskCount int, wantPrompt, wantResource []byte, +) { + t.Helper() + checkToolCount(t, tc, frames) + checkPromptSurface(t, tc.name, frames, taskCount, wantPrompt) + checkResourceSurface(t, tc.name, frames, pathCount, wantResource) +} + +func checkToolCount(t *testing.T, tc procedureModeCase, frames map[string]frame) { + t.Helper() + var tools toolsListResult + if err := json.Unmarshal(frames["1"].Result, &tools); err != nil { + t.Fatal(err) + } + if len(tools.Tools) != tc.tools { + t.Fatalf("%s tools = %d, want %d", tc.name, len(tools.Tools), tc.tools) + } +} + +func checkPromptSurface(t *testing.T, name string, frames map[string]frame, taskCount int, want []byte) { + t.Helper() + var prompts promptsListResult + if err := json.Unmarshal(frames["2"].Result, &prompts); err != nil { + t.Fatal(err) + } + if len(prompts.Prompts) != taskCount { + t.Fatalf("%s prompts = %d, want %d", name, len(prompts.Prompts), taskCount) + } + var prompt promptResult + if err := json.Unmarshal(frames["3"].Result, &prompt); err != nil { + t.Fatal(err) + } + if len(prompt.Messages) != 1 || !bytes.Equal([]byte(prompt.Messages[0].Content.Text), want) { + t.Fatalf("%s review prompt does not carry the binary's Procedure", name) + } +} + +func checkResourceSurface(t *testing.T, name string, frames map[string]frame, pathCount int, want []byte) { + t.Helper() + var resources resourceListResult + if err := json.Unmarshal(frames["4"].Result, &resources); err != nil { + t.Fatal(err) + } + if len(resources.Resources) != pathCount { + t.Fatalf("%s resources = %d, want %d", name, len(resources.Resources), pathCount) + } + var content resourceReadResult + if err := json.Unmarshal(frames["5"].Result, &content); err != nil { + t.Fatal(err) + } + if len(content.Contents) != 1 || !bytes.Equal([]byte(content.Contents[0].Text), want) { + t.Fatalf("%s PROCEDURE.md resource is not byte-identical to skill show", name) + } +} + +type procedureWire struct { + promptsList json.RawMessage + promptGet json.RawMessage + resourcesList json.RawMessage + resourceRead json.RawMessage +} + +func procedureWireFrom(frames map[string]frame) procedureWire { + return procedureWire{ + promptsList: frames["2"].Result, + promptGet: frames["3"].Result, + resourcesList: frames["4"].Result, + resourceRead: frames["5"].Result, + } +} + +func checkProcedureWire(t *testing.T, name string, got, want *procedureWire) { + t.Helper() + if !bytes.Equal(got.promptsList, want.promptsList) { + t.Errorf("%s prompts/list differs from the default surface", name) + } + if !bytes.Equal(got.promptGet, want.promptGet) { + t.Errorf("%s prompts/get differs from the default surface", name) + } + if !bytes.Equal(got.resourcesList, want.resourcesList) { + t.Errorf("%s resources/list differs from the default surface", name) + } + if !bytes.Equal(got.resourceRead, want.resourceRead) { + t.Errorf("%s resources/read differs from the default surface", name) + } +} diff --git a/internal/mcp/prompts.go b/internal/mcp/prompts.go new file mode 100644 index 00000000..13f0e16c --- /dev/null +++ b/internal/mcp/prompts.go @@ -0,0 +1,99 @@ +package mcp + +import ( + "encoding/json" + "errors" + "strconv" + "strings" + + skillfs "github.com/stainless-code/verdict" +) + +const ( + methodPromptsList = "prompts/list" + methodPromptsGet = "prompts/get" +) + +// promptDescriptions is the host-facing copy for the tasks in skillfs.Tasks. +var promptDescriptions = map[string]string{ + "address-reviews": "Address review threads with verified fixes and one reply per thread.", + "fix-ci": "Diagnose a PR-introduced CI failure, fix it, and push the fix with a summary.", + "incremental-review": "Review only the commits added since a prior review, with a no-review note for trivial deltas.", + "review": "Review a fetched PR or local diff and write one review.json.", + "validate": "Validate candidate findings against the bundle without changing it.", +} + +func (s *Server) handlePromptsList(req *rpcRequest) { + if len(req.ID) == 0 { + return + } + prompts := make([]promptDescriptor, 0, len(promptDescriptions)) + for _, task := range skillfs.Tasks() { + prompts = append(prompts, promptDescriptor{ + Name: task, + Description: promptDescriptions[task], + }) + } + s.writeResult(req.ID, promptsListResult{Prompts: prompts}) +} + +func (s *Server) handlePromptsGet(req *rpcRequest) { + if len(req.ID) == 0 { + return + } + params, ok := decodeParams[promptNameParams](req.Params) + if !ok || params.Name == "" { + s.writeInvalidPrompt(req.ID, "") + return + } + body, err := skillfs.TaskProcedure(params.Name) + if err != nil { + if _, ok := errors.AsType[*skillfs.UnknownTaskError](err); ok { + s.writeInvalidPrompt(req.ID, params.Name) + return + } + s.writeError(req.ID, codeInternalError, "prompt unavailable: "+err.Error()) + return + } + s.writeResult(req.ID, getPromptResult{ + Description: promptDescriptions[params.Name], + Messages: []promptMessage{{ + Role: "user", + Content: contentBlock{Type: contentTypeText, Text: string(body)}, + }}, + }) +} + +// MCP 2025-06-18 § server/prompts error handling: an invalid prompt name is +// -32602. The message names the served tasks because this server has no +// prompt arguments. +func (s *Server) writeInvalidPrompt(id json.RawMessage, name string) { + message := "missing prompt name; valid tasks: " + strings.Join(skillfs.Tasks(), ", ") + if name != "" { + message = "unknown prompt " + strconv.Quote(name) + "; valid tasks: " + strings.Join(skillfs.Tasks(), ", ") + } + s.writeError(id, codeInvalidParams, message) +} + +type promptNameParams struct { + Name string `json:"name"` +} + +type promptDescriptor struct { + Name string `json:"name"` + Description string `json:"description"` +} + +type promptsListResult struct { + Prompts []promptDescriptor `json:"prompts"` +} + +type promptMessage struct { + Role string `json:"role"` + Content contentBlock `json:"content"` +} + +type getPromptResult struct { + Description string `json:"description"` + Messages []promptMessage `json:"messages"` +} diff --git a/internal/mcp/prompts_test.go b/internal/mcp/prompts_test.go new file mode 100644 index 00000000..33f8e82b --- /dev/null +++ b/internal/mcp/prompts_test.go @@ -0,0 +1,203 @@ +package mcp + +import ( + "bytes" + "encoding/json" + "fmt" + "strconv" + "strings" + "testing" + + skillfs "github.com/stainless-code/verdict" +) + +// promptCopy is the exact one-line description each task advertises to hosts. +var promptCopy = map[string]string{ + "address-reviews": "Address review threads with verified fixes and one reply per thread.", + "fix-ci": "Diagnose a PR-introduced CI failure, fix it, and push the fix with a summary.", + "incremental-review": "Review only the commits added since a prior review, with a no-review note for trivial deltas.", + "review": "Review a fetched PR or local diff and write one review.json.", + "validate": "Validate candidate findings against the bundle without changing it.", +} + +type promptResult struct { + Description string `json:"description"` + Messages []struct { + Role string `json:"role"` + Content struct { + Type string `json:"type"` + Text string `json:"text"` + } `json:"content"` + } `json:"messages"` +} + +// TestPromptsListSnapshot pins the advertised names and their user-facing copy. +func TestPromptsListSnapshot(t *testing.T) { + t.Parallel() + cfg := testConfig() + frames := serve(t, &cfg, `{"jsonrpc":"2.0","id":1,"method":"prompts/list"}`) + if frames["1"].Error != nil { + t.Fatalf("prompts/list error = %+v", frames["1"].Error) + } + var result struct { + Prompts []map[string]any `json:"prompts"` + } + if err := json.Unmarshal(frames["1"].Result, &result); err != nil { + t.Fatal(err) + } + if len(result.Prompts) != len(promptCopy) { + t.Fatalf("prompts = %d, want %d", len(result.Prompts), len(promptCopy)) + } + for _, prompt := range result.Prompts { + checkPromptDescriptor(t, prompt) + } +} + +func checkPromptDescriptor(t *testing.T, prompt map[string]any) { + t.Helper() + if len(prompt) != 2 { + t.Errorf("prompt fields = %v, want only name and description", prompt) + } + name, ok := prompt["name"].(string) + if !ok { + t.Fatalf("prompt has no name: %v", prompt) + } + want, known := promptCopy[name] + if !known { + t.Errorf("prompts/list advertises unknown task %q", name) + return + } + if prompt["description"] != want { + t.Errorf("%s description = %v, want %q", name, prompt["description"], want) + } +} + +// TestPromptsGetBodies proves each prompt carries its exact task Procedure. +// The expected bodies come from literal file lists, never from TaskProcedure. +func TestPromptsGetBodies(t *testing.T) { + t.Parallel() + expected := expectedPromptBodies(t) + tasks := skillfs.Tasks() + frames := servePromptGets(t, tasks) + for i, task := range tasks { + checkPromptBody(t, frames[strconv.Itoa(i+1)], task, expected[task]) + } + assertNamedProcedure(t, frames[taskFrameID(tasks, "review")].Result, "review", skillfs.ReviewProcedure) + assertNamedProcedure(t, frames[taskFrameID(tasks, "address-reviews")].Result, + "address-reviews", skillfs.DrainProcedure) +} + +func expectedPromptBodies(t *testing.T) map[string][]byte { + t.Helper() + return map[string][]byte{ + "address-reviews": literalProcedure(t, + "PROCEDURE.md", "prompts/system.md", "prompts/address-reviews.md"), + "fix-ci": literalProcedure(t, + "PROCEDURE.md", "prompts/system.md", "prompts/fix-ci.md"), + "incremental-review": literalProcedure(t, + "PROCEDURE.md", "prompts/system.md", "prompts/incremental-review.md"), + "review": literalProcedure(t, + "PROCEDURE.md", "prompts/system.md", "prompts/review.md", "prompts/diagrams.md"), + "validate": literalProcedure(t, + "PROCEDURE.md", "prompts/system.md", "prompts/validate.md"), + } +} + +func servePromptGets(t *testing.T, tasks []string) map[string]frame { + t.Helper() + lines := make([]string, 0, len(tasks)) + for i, task := range tasks { + lines = append(lines, fmt.Sprintf( + `{"jsonrpc":"2.0","id":%d,"method":"prompts/get","params":{"name":%q}}`, i+1, task)) + } + cfg := testConfig() + return serve(t, &cfg, lines...) +} + +func checkPromptBody(t *testing.T, got frame, task string, want []byte) { + t.Helper() + if got.Error != nil { + t.Fatalf("prompts/get %s error = %+v", task, got.Error) + } + var result promptResult + if err := json.Unmarshal(got.Result, &result); err != nil { + t.Fatal(err) + } + if result.Description != promptCopy[task] { + t.Errorf("%s result description = %q, want %q", task, result.Description, promptCopy[task]) + } + if len(result.Messages) != 1 { + t.Fatalf("%s messages = %d, want one", task, len(result.Messages)) + } + message := result.Messages[0] + if message.Role != "user" || message.Content.Type != contentTypeText { + t.Errorf("%s message = %+v, want one user text block", task, message) + } + if !bytes.Equal([]byte(message.Content.Text), want) { + t.Errorf("%s text differs from the literal %d-byte Procedure", task, len(want)) + } +} + +// TestPromptUnknownName pins the spec's invalid-params refusal and its list of +// valid task names for both an unknown and a missing name. +func TestPromptUnknownName(t *testing.T) { + t.Parallel() + cfg := testConfig() + frames := serve(t, &cfg, + `{"jsonrpc":"2.0","id":1,"method":"prompts/get","params":{"name":"nope"}}`, + `{"jsonrpc":"2.0","id":2,"method":"prompts/get","params":{}}`) + checkInvalidPrompt(t, frames["1"], "nope") + checkInvalidPrompt(t, frames["2"], "") +} + +func checkInvalidPrompt(t *testing.T, got frame, name string) { + t.Helper() + if got.Error == nil || got.Error.Code != codeInvalidParams { + t.Fatalf("prompts/get %q = %+v, want -32602", name, got.Error) + } + for _, task := range skillfs.Tasks() { + if !strings.Contains(got.Error.Message, task) { + t.Errorf("prompts/get %q message %q omits %q", name, got.Error.Message, task) + } + } + if name != "" && !strings.Contains(got.Error.Message, name) { + t.Errorf("unknown prompt message = %q, want the bad name", got.Error.Message) + } +} + +func literalProcedure(t *testing.T, files ...string) []byte { + t.Helper() + var want []byte + for _, name := range files { + part, err := skillfs.Read(name) + if err != nil { + t.Fatal(err) + } + want = append(want, part...) + } + return want +} + +func taskFrameID(tasks []string, want string) string { + for i, name := range tasks { + if name == want { + return strconv.Itoa(i + 1) + } + } + return "0" +} + +func assertNamedProcedure(t *testing.T, raw json.RawMessage, task string, named func() ([]byte, error)) { + t.Helper() + var result promptResult + if err := json.Unmarshal(raw, &result); err != nil { + t.Fatal(err) + } + want, err := named() + if err != nil { + t.Fatal(err) + } + if len(result.Messages) != 1 || !bytes.Equal([]byte(result.Messages[0].Content.Text), want) { + t.Errorf("%s text differs from its named Procedure", task) + } +} diff --git a/internal/mcp/resources.go b/internal/mcp/resources.go new file mode 100644 index 00000000..3c3fed90 --- /dev/null +++ b/internal/mcp/resources.go @@ -0,0 +1,125 @@ +package mcp + +import ( + "context" + "encoding/json" + "path" + "strconv" + "strings" + + "github.com/stainless-code/verdict/internal/core/skill" +) + +const ( + methodResourcesList = "resources/list" + methodResourcesRead = "resources/read" + resourceURIPrefix = "verdict://skill/" + codeResourceNotFound = -32002 +) + +func (s *Server) handleResourcesList(ctx context.Context, req *rpcRequest) { + if len(req.ID) == 0 { + return + } + inv, ref := skill.List(ctx, &skill.Request{}) + if ref != nil { + s.writeError(req.ID, codeInternalError, "resource list unavailable: "+ref.Message) + return + } + resources := make([]resourceDescriptor, 0, len(inv.Files)) + for _, name := range inv.Files { + resources = append(resources, resourceDescriptor{ + URI: resourceURIPrefix + name, + Name: name, + MIMEType: resourceMIMEType(name), + }) + } + s.writeResult(req.ID, resourcesListResult{Resources: resources}) +} + +func (s *Server) handleResourcesRead(ctx context.Context, req *rpcRequest) { + if len(req.ID) == 0 { + return + } + params, ok := decodeParams[resourceURIParams](req.Params) + if !ok { + s.writeResourceNotFound(req.ID, "") + return + } + name, valid := payloadPath(params.URI) + if !valid { + s.writeResourceNotFound(req.ID, params.URI) + return + } + body, ref := skill.ShowFile(ctx, &skill.Request{}, name) + if ref != nil { + s.writeResourceNotFound(req.ID, params.URI) + return + } + s.writeResult(req.ID, readResourceResult{Contents: []resourceContent{{ + URI: params.URI, + MIMEType: resourceMIMEType(name), + Text: string(body), + }}}) +} + +// payloadPath accepts exactly one embedded payload path after the served URI +// prefix. Query markers, escapes, absolute paths, and dot segments are refused +// before any service call, so no read can resolve outside the payload. +func payloadPath(uri string) (string, bool) { + name, ok := strings.CutPrefix(uri, resourceURIPrefix) + if !ok || name == "" || strings.ContainsAny(name, "?#%\\") { + return "", false + } + if path.Clean(name) != name || strings.HasPrefix(name, "/") || + name == "." || name == ".." || strings.HasPrefix(name, "../") { + return "", false + } + return name, true +} + +func resourceMIMEType(name string) string { + switch path.Ext(name) { + case ".md": + return "text/markdown" + case ".json": + return "application/json" + default: + return "text/plain" + } +} + +// MCP 2025-06-18 § server/resources error handling: a missing resource is +// -32002, and the spec's example carries the URI in the message and error data. +func (s *Server) writeResourceNotFound(id json.RawMessage, uri string) { + s.writeErrorData(id, codeResourceNotFound, "resource not found: "+strconv.Quote(uri), + resourceNotFoundData{URI: uri}) +} + +type resourceURIParams struct { + URI string `json:"uri"` +} + +type resourceDescriptor struct { + URI string `json:"uri"` + Name string `json:"name"` + MIMEType string `json:"mimeType"` +} + +type resourcesListResult struct { + Resources []resourceDescriptor `json:"resources"` +} + +type resourceContent struct { + URI string `json:"uri"` + MIMEType string `json:"mimeType"` + Text string `json:"text"` +} + +type readResourceResult struct { + Contents []resourceContent `json:"contents"` +} + +type resourceNotFoundData struct { + URI string `json:"uri"` +} diff --git a/internal/mcp/resources_test.go b/internal/mcp/resources_test.go new file mode 100644 index 00000000..d6674081 --- /dev/null +++ b/internal/mcp/resources_test.go @@ -0,0 +1,198 @@ +package mcp + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "strconv" + "strings" + "testing" + + skillfs "github.com/stainless-code/verdict" + "github.com/stainless-code/verdict/internal/core/skill" +) + +const resourcePrefix = "verdict://skill/" + +var literalMIME = map[string]string{ + "PROCEDURE.md": "text/markdown", + "schemas/review.schema.json": "application/json", + "scripts/verdict": "text/plain", +} + +type resourceDescriptorFrame struct { + URI string `json:"uri"` + Name string `json:"name"` + MIMEType string `json:"mimeType"` +} + +type resourceListResult struct { + Resources []resourceDescriptorFrame `json:"resources"` +} + +type resourceReadResult struct { + Contents []struct { + URI string `json:"uri"` + MIMEType string `json:"mimeType"` + Text string `json:"text"` + } `json:"contents"` +} + +// TestResourcesListInventory pins one descriptor per served payload path. +func TestResourcesListInventory(t *testing.T) { + t.Parallel() + cfg := testConfig() + frames := serve(t, &cfg, `{"jsonrpc":"2.0","id":1,"method":"resources/list"}`) + if frames["1"].Error != nil { + t.Fatalf("resources/list error = %+v", frames["1"].Error) + } + var result resourceListResult + if err := json.Unmarshal(frames["1"].Result, &result); err != nil { + t.Fatal(err) + } + paths, err := skillfs.Paths() + if err != nil { + t.Fatal(err) + } + if len(result.Resources) != len(paths) { + t.Fatalf("resources = %d, want the %d served paths", len(result.Resources), len(paths)) + } + for i, path := range paths { + checkResourceDescriptor(t, i, path, result.Resources[i]) + } + checkLiteralMIMEs(t, result.Resources) +} + +func checkResourceDescriptor(t *testing.T, i int, path string, got resourceDescriptorFrame) { + t.Helper() + if want := resourcePrefix + path; got.URI != want { + t.Errorf("resource %d uri = %q, want %q", i, got.URI, want) + } + if got.Name != path { + t.Errorf("resource %d name = %q, want %q", i, got.Name, path) + } + if want := literalMIMEFor(path); got.MIMEType != want { + t.Errorf("%s mimeType = %q, want %q", path, got.MIMEType, want) + } +} + +func checkLiteralMIMEs(t *testing.T, resources []resourceDescriptorFrame) { + t.Helper() + for path, want := range literalMIME { + got, found := resourceNamed(resources, path) + if !found { + t.Errorf("resources/list misses literal MIME case %q", path) + continue + } + if got.MIMEType != want { + t.Errorf("%s mimeType = %q, want literal %q", path, got.MIMEType, want) + } + } +} + +func resourceNamed(resources []resourceDescriptorFrame, path string) (resourceDescriptorFrame, bool) { + for _, resource := range resources { + if resource.Name == path { + return resource, true + } + } + return resourceDescriptorFrame{}, false +} + +// TestResourcesReadMatchesSkillShow proves every served path reads back the +// same bytes and mime type the skill service gives `verdict skill show`. +func TestResourcesReadMatchesSkillShow(t *testing.T) { + t.Parallel() + paths, err := skillfs.Paths() + if err != nil { + t.Fatal(err) + } + frames := serveResourceReads(t, paths) + for i, path := range paths { + checkResourceRead(t, path, frames[strconv.Itoa(i+1)]) + } +} + +func serveResourceReads(t *testing.T, paths []string) map[string]frame { + t.Helper() + lines := make([]string, 0, len(paths)) + for i, path := range paths { + lines = append(lines, fmt.Sprintf( + `{"jsonrpc":"2.0","id":%d,"method":"resources/read","params":{"uri":%q}}`, + i+1, resourcePrefix+path)) + } + cfg := testConfig() + return serve(t, &cfg, lines...) +} + +func checkResourceRead(t *testing.T, path string, got frame) { + t.Helper() + if got.Error != nil { + t.Fatalf("resources/read %s error = %+v", path, got.Error) + } + var result resourceReadResult + if err := json.Unmarshal(got.Result, &result); err != nil { + t.Fatal(err) + } + if len(result.Contents) != 1 { + t.Fatalf("%s contents = %d, want one", path, len(result.Contents)) + } + content := result.Contents[0] + if content.URI != resourcePrefix+path || content.MIMEType != literalMIMEFor(path) { + t.Errorf("%s content = %+v, want its URI and mime type", path, content) + } + want, ref := skill.ShowFile(context.Background(), &skill.Request{}, path) + if ref != nil { + t.Fatalf("skill show %s: %v", path, ref) + } + if !bytes.Equal([]byte(content.Text), want) { + t.Errorf("resources/read %s differs from skill show bytes", path) + } +} + +// TestResourcesReadRefusesBadURIs pins -32002 for unknown, foreign, traversal, +// absolute, and empty paths. The URI appears in every message. +func TestResourcesReadRefusesBadURIs(t *testing.T) { + t.Parallel() + uris := []string{ + resourcePrefix + "nope.md", + "file:///etc/passwd", + resourcePrefix + "../PROCEDURE.md", + resourcePrefix + "prompts/../../PROCEDURE.md", + resourcePrefix + "/PROCEDURE.md", + resourcePrefix + "%2e%2e/PROCEDURE.md", + resourcePrefix, + } + lines := make([]string, 0, len(uris)) + for i, uri := range uris { + lines = append(lines, fmt.Sprintf( + `{"jsonrpc":"2.0","id":%d,"method":"resources/read","params":{"uri":%q}}`, i+1, uri)) + } + cfg := testConfig() + frames := serve(t, &cfg, lines...) + for i, uri := range uris { + checkResourceRefusal(t, uri, frames[strconv.Itoa(i+1)]) + } +} + +func checkResourceRefusal(t *testing.T, uri string, got frame) { + t.Helper() + if got.Error == nil || got.Error.Code != codeResourceNotFound { + t.Fatalf("resources/read %q = %+v, want -32002", uri, got.Error) + } + if !strings.Contains(got.Error.Message, uri) { + t.Errorf("resources/read %q message = %q, want the URI", uri, got.Error.Message) + } +} + +func literalMIMEFor(path string) string { + switch { + case strings.HasSuffix(path, ".md"): + return "text/markdown" + case strings.HasSuffix(path, ".json"): + return "application/json" + default: + return "text/plain" + } +} diff --git a/internal/mcp/server.go b/internal/mcp/server.go index 15b1e776..15bc6006 100644 --- a/internal/mcp/server.go +++ b/internal/mcp/server.go @@ -39,6 +39,7 @@ const ( codeInvalidRequest = -32600 codeMethodNotFound = -32601 codeInvalidParams = -32602 + codeInternalError = -32603 contentTypeText = "text" refusalTextLines = 3 lineBreak = "\n" @@ -46,6 +47,8 @@ const ( scannerInitialBytes = 64 * 1024 ) +const capabilityListChanged = "listChanged" + // supportedProtocols are the MCP revisions the server can speak. var supportedProtocols = []string{"2024-11-05", "2025-03-26", latestProtocol} @@ -251,6 +254,8 @@ func (s *Server) dispatch(ctx context.Context, req *rpcRequest) { s.writeResult(req.ID, s.listTools()) case methodToolsCall: s.handleToolsCall(ctx, req) + case methodPromptsList, methodPromptsGet, methodResourcesList, methodResourcesRead: + s.handleProcedure(ctx, req) case methodCancelled: s.handleCancelled(req) default: @@ -260,6 +265,20 @@ func (s *Server) dispatch(ctx context.Context, req *rpcRequest) { } } +// handleProcedure routes the read-only prompt and resource methods. +func (s *Server) handleProcedure(ctx context.Context, req *rpcRequest) { + switch req.Method { + case methodPromptsList: + s.handlePromptsList(req) + case methodPromptsGet: + s.handlePromptsGet(req) + case methodResourcesList: + s.handleResourcesList(ctx, req) + case methodResourcesRead: + s.handleResourcesRead(ctx, req) + } +} + func (s *Server) handleInitialize(req *rpcRequest) { if len(req.ID) == 0 { return @@ -271,7 +290,11 @@ func (s *Server) handleInitialize(req *rpcRequest) { } s.writeResult(req.ID, initializeResult{ ProtocolVersion: negotiate(params.ProtocolVersion), - Capabilities: map[string]any{"tools": map[string]any{"listChanged": false}}, + Capabilities: map[string]any{ + "prompts": map[string]any{capabilityListChanged: false}, + "resources": map[string]any{capabilityListChanged: false, "subscribe": false}, + "tools": map[string]any{capabilityListChanged: false}, + }, ServerInfo: serverInfo{ Name: serverName, Version: s.cfg.Version, @@ -284,6 +307,7 @@ func (s *Server) handleInitialize(req *rpcRequest) { func (s *Server) instructions() string { lines := []string{ "Review one pull request at a time: fetch, read .verdict/state/, write exactly one review.json, then post.", + "For the Procedure, use the review prompt or read verdict://skill/PROCEDURE.md.", "Use report, next, or show to rank and inspect findings; refusals carry a hint, so follow it.", "post is the only terminal write and never writes a review note; dryRun previews it.", "Never call triage while reviewing a PR: propose status changes through triage[] in review.json.", diff --git a/scripts/size-baseline.txt b/scripts/size-baseline.txt index 42efbb4b..9f45b21c 100644 --- a/scripts/size-baseline.txt +++ b/scripts/size-baseline.txt @@ -1,7 +1,7 @@ deps 0 -darwin/amd64 17640000 -darwin/arm64 16040000 -linux/amd64 17330000 -linux/arm64 15670000 -windows/amd64 17730000 -windows/arm64 15810000 +darwin/amd64 17660000 +darwin/arm64 16080000 +linux/amd64 17360000 +linux/arm64 15740000 +windows/amd64 17750000 +windows/arm64 15830000 diff --git a/skillfs.go b/skillfs.go index b66e6eb1..e3e857be 100644 --- a/skillfs.go +++ b/skillfs.go @@ -12,6 +12,7 @@ import ( "fmt" "io" "io/fs" + "maps" "slices" "strings" ) @@ -249,14 +250,53 @@ func (e *ProcedureFileError) Error() string { // Unwrap exposes the underlying read failure. func (e *ProcedureFileError) Unwrap() error { return e.Cause } +const systemPromptMD = "prompts/system.md" + // reviewProcedureFiles is the review assembly's trust order, in one place. func reviewProcedureFiles() []string { - return []string{ProcedureMD, "prompts/system.md", "prompts/review.md", "prompts/diagrams.md"} + return []string{ProcedureMD, systemPromptMD, "prompts/review.md", "prompts/diagrams.md"} } // drainProcedureFiles is the drain assembly's trust order, in one place. func drainProcedureFiles() []string { - return []string{ProcedureMD, "prompts/system.md", "prompts/address-reviews.md"} + return []string{ProcedureMD, systemPromptMD, "prompts/address-reviews.md"} +} + +// taskFiles is the single task vocabulary: each name maps to its assembly in +// the order the Procedure's mode router trusts the files. +var taskFiles = map[string]func() []string{ + "address-reviews": drainProcedureFiles, + "fix-ci": func() []string { return genericTaskFiles("fix-ci") }, + "incremental-review": func() []string { return genericTaskFiles("incremental-review") }, + "review": reviewProcedureFiles, + "validate": func() []string { return genericTaskFiles("validate") }, +} + +func genericTaskFiles(task string) []string { + return []string{ProcedureMD, systemPromptMD, "prompts/" + task + ".md"} +} + +// Tasks lists the Procedure tasks this binary serves, sorted by name. +func Tasks() []string { return slices.Sorted(maps.Keys(taskFiles)) } + +// UnknownTaskError names a task this binary does not serve. Callers inspect it +// with [errors.As]. +type UnknownTaskError struct { + Task string +} + +// Error reports the unknown task name. +func (e *UnknownTaskError) Error() string { return "unknown task: " + e.Task } + +// TaskProcedure returns one task's Procedure, assembled from the embedded +// payload in the same trust order the bundle uses. It never reads the +// filesystem. An unknown task returns no bytes and an [UnknownTaskError]. +func TaskProcedure(task string) ([]byte, error) { + files, ok := taskFiles[task] + if !ok { + return nil, &UnknownTaskError{Task: task} + } + return assembleProcedure(files()) } // assembleProcedure concatenates the named embedded files in order. A missing @@ -278,8 +318,8 @@ func assembleProcedure(files []string) ([]byte, error) { // PROCEDURE.md, prompts/system.md, prompts/review.md, and prompts/diagrams.md, // concatenated in that trust order. It never reads the filesystem. A missing // file returns no bytes and a ProcedureFileError; fetch and --show-prompts -// refuse the whole run as prompt-dump-failed. PR 3's MCP prompts reuse this -// public contract. +// refuse the whole run as prompt-dump-failed. MCP prompts reuse this public +// contract. func ReviewProcedure() ([]byte, error) { return assembleProcedure(reviewProcedureFiles()) } @@ -288,8 +328,7 @@ func ReviewProcedure() ([]byte, error) { // PROCEDURE.md, prompts/system.md, and prompts/address-reviews.md, concatenated // in that trust order. It never reads the filesystem. A missing file returns // no bytes and a ProcedureFileError; the drain bundle writer refuses rather -// than publishing a partial Procedure. PR 3's MCP prompts reuse this public -// contract. +// than publishing a partial Procedure. MCP prompts reuse this public contract. func DrainProcedure() ([]byte, error) { return assembleProcedure(drainProcedureFiles()) } diff --git a/taskprocedure_test.go b/taskprocedure_test.go new file mode 100644 index 00000000..d9220075 --- /dev/null +++ b/taskprocedure_test.go @@ -0,0 +1,115 @@ +package skillfs_test + +import ( + "bytes" + "errors" + "slices" + "testing" + + skillfs "github.com/stainless-code/verdict" +) + +// wantTasks is the task vocabulary written into the Procedure's mode router. +// It is a literal, not a copy of the list under test. +var wantTasks = []string{"address-reviews", "fix-ci", "incremental-review", "review", "validate"} + +// TestTasks pins the served task names and their order. +func TestTasks(t *testing.T) { + t.Parallel() + if got := skillfs.Tasks(); !slices.Equal(got, wantTasks) { + t.Fatalf("Tasks() = %v, want %v", got, wantTasks) + } +} + +type taskAssemblyCase struct { + task string + files []string +} + +// TestTaskProcedureAssemblies pins every body to the files its task names. +// The generic expectations use literal file lists read through skillfs.Read, +// never TaskProcedure or the assembly loop under test. +func TestTaskProcedureAssemblies(t *testing.T) { + t.Parallel() + for _, tc := range []taskAssemblyCase{ + {files: []string{"PROCEDURE.md", "prompts/system.md", "prompts/incremental-review.md"}, task: "incremental-review"}, + {files: []string{"PROCEDURE.md", "prompts/system.md", "prompts/fix-ci.md"}, task: "fix-ci"}, + {files: []string{"PROCEDURE.md", "prompts/system.md", "prompts/validate.md"}, task: "validate"}, + } { + t.Run(tc.task, func(t *testing.T) { + t.Parallel() + checkTaskAssembly(t, tc) + }) + } +} + +func checkTaskAssembly(t *testing.T, tc taskAssemblyCase) { + t.Helper() + var want []byte + for _, name := range tc.files { + part, err := skillfs.Read(name) + if err != nil { + t.Fatal(err) + } + want = append(want, part...) + } + got, err := skillfs.TaskProcedure(tc.task) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(got, want) { + t.Fatalf("TaskProcedure(%q) differs from the literal assembly of %v", tc.task, tc.files) + } +} + +type namedProcedureCase struct { + want func() ([]byte, error) + task string +} + +// TestTaskProcedureReusesProcedureBodies pins the two named assemblies to the +// public functions the bundle already uses. +func TestTaskProcedureReusesProcedureBodies(t *testing.T) { + t.Parallel() + for _, tc := range []namedProcedureCase{ + {want: skillfs.ReviewProcedure, task: "review"}, + {want: skillfs.DrainProcedure, task: "address-reviews"}, + } { + t.Run(tc.task, func(t *testing.T) { + t.Parallel() + checkNamedProcedureBody(t, tc) + }) + } +} + +func checkNamedProcedureBody(t *testing.T, tc namedProcedureCase) { + t.Helper() + want, err := tc.want() + if err != nil { + t.Fatal(err) + } + got, err := skillfs.TaskProcedure(tc.task) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(got, want) { + t.Fatalf("TaskProcedure(%q) differs from its named Procedure", tc.task) + } +} + +// TestTaskProcedureUnknownTask pins the typed refusal for a name outside the +// served vocabulary. +func TestTaskProcedureUnknownTask(t *testing.T) { + t.Parallel() + got, err := skillfs.TaskProcedure("nope") + if got != nil { + t.Fatalf("TaskProcedure(unknown) returned %d bytes", len(got)) + } + unknown, ok := errors.AsType[*skillfs.UnknownTaskError](err) + if !ok { + t.Fatalf("TaskProcedure(unknown) error = %v, want *UnknownTaskError", err) + } + if want := "unknown task: nope"; unknown.Error() != want { + t.Errorf("UnknownTaskError = %q, want %q", unknown.Error(), want) + } +}