Land staged session/MCP/chrome work + sidebar clear-J fix
This batches the in-flight [Unreleased] block from CHANGELOG.md into a single commit. Highlights: - Real MCP protocol layer (initialize / tools/list / tools/call) so vendor MCP clients can complete the handshake against the per-PID socket. Legacy direct-dispatch preserved for the harness. - New mcp_injection kinds — cli_override for codex, config_env for opencode — joining the existing env-var and config_file paths so patterm can slot into more agents without touching their real config or auth. - Ctrl+A/D and Ctrl+W/S focus navigation across tabs and intra-tab process lists, recognised in legacy / kitty CSI u / xterm modifyOtherKeys encodings. - Palette macros (sw / k / sp ) and reordering so open sessions surface above spawn-new entries. - Two-row tab bar, sidebar/tabbar/status chrome cache, viewport-wipe on agent spawn, CR-terminated orchestrator injections, and split- Enter PTY writes so paste-detecting TUIs see Enter as a key event. Also fixes the bug logged in TODO: claude's Ctrl+O tool-call expansion emits CSI 0 J, which the viewport renderer was forwarding verbatim — wiping the sidebar to the right of the cursor and leaving the chrome cache convinced nothing had changed. CSI 0 J and CSI 1 J are now translated into per-row ECH sequences clamped to the viewport, same as CSI 2 J and CSI K already were. Agent guides (CLAUDE.md / AGENTS.md) now spell out the TODO->CHANGELOG workflow so completed items land in the changelog rather than as ticked entries left behind in TODO.
This commit is contained in:
415
internal/mcp/protocol.go
Normal file
415
internal/mcp/protocol.go
Normal file
@@ -0,0 +1,415 @@
|
||||
package mcp
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
)
|
||||
|
||||
// MCP protocol surface. The patterm server originally exposed each
|
||||
// tool as its own JSON-RPC method (and the harness still drives it
|
||||
// that way). Real MCP clients (claude, codex, opencode) speak the
|
||||
// model-context-protocol RPC dialect: they send `initialize` first,
|
||||
// then `tools/list`, then `tools/call` with `{name, arguments}`. This
|
||||
// file wraps those four entry points around the existing tool dispatch
|
||||
// without changing the underlying tool implementations.
|
||||
|
||||
// supportedProtocolVersion is the MCP protocol revision we advertise
|
||||
// when a client doesn't pin a specific version. Claude Code accepts
|
||||
// the dated-string scheme used by the MCP spec.
|
||||
const supportedProtocolVersion = "2025-06-18"
|
||||
|
||||
// serverInfo identifies the server back to the client during the
|
||||
// initialize handshake. The version is intentionally kept generic so
|
||||
// it doesn't need bumping per release; clients only key behavior off
|
||||
// name + protocol version.
|
||||
var serverInfo = map[string]any{
|
||||
"name": "patterm",
|
||||
"version": "0.1.0",
|
||||
}
|
||||
|
||||
// toolDescriptor is the shape returned by `tools/list`. inputSchema is
|
||||
// a JSON Schema object — we provide a minimal `{type: "object"}` schema
|
||||
// for each tool, which lets MCP clients accept arbitrary arguments and
|
||||
// rely on patterm's own server-side validation for typing.
|
||||
type toolDescriptor struct {
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description"`
|
||||
InputSchema map[string]any `json:"inputSchema"`
|
||||
}
|
||||
|
||||
// objectSchema builds an inputSchema for a tool that takes an object
|
||||
// with the listed properties. required lists property names that must
|
||||
// be present; passing nil makes them all optional. We always emit a
|
||||
// concrete `properties` object (never null) because some MCP clients
|
||||
// reject schemas where `properties` is not an object.
|
||||
func objectSchema(properties map[string]any, required []string) map[string]any {
|
||||
if properties == nil {
|
||||
properties = map[string]any{}
|
||||
}
|
||||
s := map[string]any{
|
||||
"type": "object",
|
||||
"properties": properties,
|
||||
"additionalProperties": true,
|
||||
}
|
||||
if len(required) > 0 {
|
||||
s["required"] = required
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
func stringProp(desc string) map[string]any {
|
||||
return map[string]any{"type": "string", "description": desc}
|
||||
}
|
||||
|
||||
func numberProp(desc string) map[string]any {
|
||||
return map[string]any{"type": "number", "description": desc}
|
||||
}
|
||||
|
||||
func integerProp(desc string) map[string]any {
|
||||
return map[string]any{"type": "integer", "description": desc}
|
||||
}
|
||||
|
||||
func booleanProp(desc string) map[string]any {
|
||||
return map[string]any{"type": "boolean", "description": desc}
|
||||
}
|
||||
|
||||
// toolCatalog is the full list advertised via tools/list. Descriptions
|
||||
// are intentionally short — clients are expected to fetch help() for
|
||||
// detail. Schemas mirror the param structs in tools.go.
|
||||
func toolCatalog() []toolDescriptor {
|
||||
return []toolDescriptor{
|
||||
{
|
||||
Name: "spawn_agent",
|
||||
Description: "Spawn a sub-agent from an agent preset and optionally seed it with initial instructions.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"agent": stringProp("Preset name (e.g. \"claude\", \"codex\")."),
|
||||
"agent_instructions": stringProp("Initial prompt typed into the agent after it's ready."),
|
||||
"name": stringProp("Display name for the new pane."),
|
||||
}, []string{"agent"}),
|
||||
},
|
||||
{
|
||||
Name: "spawn_process",
|
||||
Description: "Spawn a process: a terminal, a process preset, or a freeform argv command.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"kind": stringProp("\"terminal\" or \"command\"."),
|
||||
"preset": stringProp("Process preset name (mutually exclusive with argv)."),
|
||||
"argv": map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "Argv vector for freeform commands."},
|
||||
"name": stringProp("Display name for the pane."),
|
||||
"working_dir": stringProp("Working directory for the spawned process."),
|
||||
"env": map[string]any{"type": "object", "additionalProperties": map[string]any{"type": "string"}, "description": "Extra environment variables."},
|
||||
"shell": booleanProp("Run argv through sh -lc."),
|
||||
}, nil),
|
||||
},
|
||||
{
|
||||
Name: "start_process",
|
||||
Description: "(Re)attach a PTY to a session-persistent command process that has exited.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "restart_process",
|
||||
Description: "Signal the target process and restart it under a fresh PTY.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"signal": integerProp("Signal to send before relaunch (default SIGTERM)."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "stop_process",
|
||||
Description: "Send a signal to a running process without removing its entry.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"signal": integerProp("Signal to send (default SIGTERM)."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "close_process",
|
||||
Description: "Remove the process entry entirely; live children are SIGKILL'd first.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "rename_process",
|
||||
Description: "Rename the pane label for a process.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"name": stringProp("New display name."),
|
||||
}, []string{"process_id", "name"}),
|
||||
},
|
||||
{
|
||||
Name: "select_process",
|
||||
Description: "Focus the named process in the host TUI.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "list_processes",
|
||||
Description: "List visible processes, optionally filtered by kind (\"agent\", \"command\", \"terminal\").",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"kind": stringProp("Optional kind filter."),
|
||||
}, nil),
|
||||
},
|
||||
{
|
||||
Name: "get_process_status",
|
||||
Description: "Return rich status (status, geometry, cursor, screen version) for one process.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "get_project_status",
|
||||
Description: "One-shot orientation: project, caller, processes, scratchpads.",
|
||||
InputSchema: objectSchema(nil, nil),
|
||||
},
|
||||
{
|
||||
Name: "get_process_output",
|
||||
Description: "Read rendered grid (\"grid\") or scrollback (\"scrollback\") output, with screen-version watermark.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"mode": stringProp("\"grid\" (default) or \"scrollback\"."),
|
||||
"since_offset": integerProp("Watermark offset from a previous call."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "get_process_raw_output",
|
||||
Description: "Read the raw ANSI byte stream since since_offset.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"since_offset": integerProp("Byte offset from a previous call."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "search_output",
|
||||
Description: "Search a process's rendered or raw output and return matching lines.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"pattern": stringProp("Regex pattern."),
|
||||
"kind": stringProp("\"rendered\" (default) or \"raw\"."),
|
||||
"limit": integerProp("Max matches (default 20)."),
|
||||
}, []string{"process_id", "pattern"}),
|
||||
},
|
||||
{
|
||||
Name: "wait_for_pattern",
|
||||
Description: "Block until pattern appears in process output or timeout elapses.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"pattern": stringProp("Regex pattern."),
|
||||
"timeout_seconds": numberProp("Max time to wait (seconds)."),
|
||||
"scope": stringProp("\"new\" (default) or \"all\"."),
|
||||
}, []string{"process_id", "pattern"}),
|
||||
},
|
||||
{
|
||||
Name: "get_process_ports",
|
||||
Description: "Return URL-form port sightings observed in a process's output.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
}, []string{"process_id"}),
|
||||
},
|
||||
{
|
||||
Name: "send_input",
|
||||
Description: "Type text, paste a block, or fire a named key into a process. Optional tail-after-send.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"kind": stringProp("\"text\", \"paste\", or \"key\"."),
|
||||
"text": stringProp("Text payload for kind=text/paste."),
|
||||
"key": stringProp("Named key for kind=key (e.g. \"enter\", \"esc\")."),
|
||||
"submit": booleanProp("Whether to append a submit keystroke."),
|
||||
"wait_ms": integerProp("After sending, wait this many ms before tailing."),
|
||||
"tail_mode": stringProp("\"none\" (default), \"stream\", or \"grid\"."),
|
||||
}, []string{"process_id", "kind"}),
|
||||
},
|
||||
{
|
||||
Name: "send_message",
|
||||
Description: "Deliver a text message to another process as orchestrator-owned input.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"target_process_id": stringProp("Recipient process id."),
|
||||
"message": stringProp("Message body."),
|
||||
}, []string{"target_process_id", "message"}),
|
||||
},
|
||||
{
|
||||
Name: "request_human_attention",
|
||||
Description: "Flag a process pane as needing human review.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"process_id": stringProp("Target process id."),
|
||||
"reason": stringProp("Short description shown to the human."),
|
||||
}, []string{"process_id", "reason"}),
|
||||
},
|
||||
{
|
||||
Name: "timer_wait",
|
||||
Description: "Sleep server-side for `seconds` and return a timer id (use to pace polling).",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"seconds": numberProp("Sleep duration."),
|
||||
"label": stringProp("Optional label for diagnostics."),
|
||||
}, []string{"seconds"}),
|
||||
},
|
||||
{
|
||||
Name: "scratchpad_list",
|
||||
Description: "List shared per-project scratchpad entries.",
|
||||
InputSchema: objectSchema(nil, nil),
|
||||
},
|
||||
{
|
||||
Name: "scratchpad_read",
|
||||
Description: "Read a scratchpad entry, returning content and revision.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"name": stringProp("Scratchpad name."),
|
||||
}, []string{"name"}),
|
||||
},
|
||||
{
|
||||
Name: "scratchpad_write",
|
||||
Description: "Write a scratchpad entry with optimistic concurrency on expected_revision.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"name": stringProp("Scratchpad name."),
|
||||
"content": stringProp("New content."),
|
||||
"expected_revision": stringProp("Last-seen revision token."),
|
||||
}, []string{"name", "content"}),
|
||||
},
|
||||
{
|
||||
Name: "scratchpad_append",
|
||||
Description: "Append to a scratchpad entry without revision checking.",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"name": stringProp("Scratchpad name."),
|
||||
"content": stringProp("Text to append."),
|
||||
}, []string{"name", "content"}),
|
||||
},
|
||||
{
|
||||
Name: "whoami",
|
||||
Description: "Return the caller's identity, role, parent, project metadata, and available tools.",
|
||||
InputSchema: objectSchema(nil, nil),
|
||||
},
|
||||
{
|
||||
Name: "help",
|
||||
Description: "Return human-readable help for a topic (e.g. tool name).",
|
||||
InputSchema: objectSchema(map[string]any{
|
||||
"topic": stringProp("Topic or tool name (empty for index)."),
|
||||
}, nil),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// handleProtocolMethod handles MCP protocol-level methods. Returns
|
||||
// (result, handled). When handled is false, the caller falls back to
|
||||
// the legacy direct-tool dispatch. For notifications, result is nil
|
||||
// and handled is true.
|
||||
func (s *Server) handleProtocolMethod(callerID, method string, params json.RawMessage, isNotification bool) (any, bool, int, string, any) {
|
||||
switch method {
|
||||
case "initialize":
|
||||
var p struct {
|
||||
ProtocolVersion string `json:"protocolVersion"`
|
||||
Capabilities map[string]any `json:"capabilities"`
|
||||
ClientInfo map[string]any `json:"clientInfo"`
|
||||
}
|
||||
_ = unmarshalParamsOptional(params, &p)
|
||||
protoVersion := p.ProtocolVersion
|
||||
if protoVersion == "" {
|
||||
protoVersion = supportedProtocolVersion
|
||||
}
|
||||
result := map[string]any{
|
||||
"protocolVersion": protoVersion,
|
||||
"capabilities": map[string]any{
|
||||
"tools": map[string]any{"listChanged": false},
|
||||
},
|
||||
"serverInfo": serverInfo,
|
||||
}
|
||||
return result, true, 0, "", nil
|
||||
|
||||
case "notifications/initialized", "notifications/cancelled", "notifications/roots/list_changed":
|
||||
// Notifications get no response — handled is true so the caller
|
||||
// doesn't fall through to legacy dispatch, but result is nil.
|
||||
return nil, true, 0, "", nil
|
||||
|
||||
case "ping":
|
||||
return map[string]any{}, true, 0, "", nil
|
||||
|
||||
case "tools/list":
|
||||
return map[string]any{"tools": toolCatalog()}, true, 0, "", nil
|
||||
|
||||
case "tools/call":
|
||||
var p struct {
|
||||
Name string `json:"name"`
|
||||
Arguments json.RawMessage `json:"arguments"`
|
||||
}
|
||||
if err := unmarshalParams(params, &p); err != nil {
|
||||
return nil, true, codeInvalidParams, err.Error(), nil
|
||||
}
|
||||
if p.Name == "" {
|
||||
return nil, true, codeInvalidParams, "tools/call: name required", nil
|
||||
}
|
||||
s.mu.Lock()
|
||||
host := s.host
|
||||
s.mu.Unlock()
|
||||
if host == nil {
|
||||
return nil, true, codeInternal, "patterm: tool host not initialized", nil
|
||||
}
|
||||
result, code, errMsg, data := callTool(host, callerID, p.Name, p.Arguments)
|
||||
if errMsg != "" {
|
||||
// MCP convention: errors during tool execution come back as
|
||||
// successful tools/call results with isError=true, so the
|
||||
// model sees the failure as content rather than a transport
|
||||
// error. Genuine transport errors (parse, etc.) stay as
|
||||
// JSON-RPC errors and are handled outside this branch.
|
||||
content := errMsg
|
||||
if data != nil {
|
||||
if kindMap, ok := data.(map[string]string); ok {
|
||||
if k, present := kindMap["kind"]; present && k != "" {
|
||||
content = fmt.Sprintf("%s (%s)", errMsg, k)
|
||||
}
|
||||
}
|
||||
}
|
||||
_ = code // code stays useful for legacy callers; tools/call surfaces text.
|
||||
return map[string]any{
|
||||
"content": []map[string]any{{"type": "text", "text": content}},
|
||||
"isError": true,
|
||||
}, true, 0, "", nil
|
||||
}
|
||||
return wrapToolResult(result), true, 0, "", nil
|
||||
|
||||
case "resources/list":
|
||||
// We don't expose resources; respond with an empty list rather
|
||||
// than a method-not-found to keep clients happy.
|
||||
return map[string]any{"resources": []any{}}, true, 0, "", nil
|
||||
|
||||
case "prompts/list":
|
||||
return map[string]any{"prompts": []any{}}, true, 0, "", nil
|
||||
|
||||
case "logging/setLevel":
|
||||
return map[string]any{}, true, 0, "", nil
|
||||
}
|
||||
return nil, false, 0, "", nil
|
||||
}
|
||||
|
||||
// wrapToolResult turns a structured tool result into an MCP tools/call
|
||||
// response. Plain strings (e.g. "ok") become text content; structured
|
||||
// values are JSON-encoded into a single text block and also exposed
|
||||
// under structuredContent so capable clients can read the shape.
|
||||
func wrapToolResult(result any) map[string]any {
|
||||
var text string
|
||||
switch v := result.(type) {
|
||||
case nil:
|
||||
text = "ok"
|
||||
case string:
|
||||
text = v
|
||||
default:
|
||||
b, err := json.Marshal(v)
|
||||
if err != nil {
|
||||
text = fmt.Sprintf("%v", v)
|
||||
} else {
|
||||
text = string(b)
|
||||
}
|
||||
}
|
||||
out := map[string]any{
|
||||
"content": []map[string]any{{"type": "text", "text": text}},
|
||||
"isError": false,
|
||||
}
|
||||
if result != nil {
|
||||
switch result.(type) {
|
||||
case string:
|
||||
// Skip — plain string already lives in content.
|
||||
default:
|
||||
out["structuredContent"] = result
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
Reference in New Issue
Block a user