vanyangyang/cursor-bridge/grok-build-supervisor

Grok Build Supervisor

Use the grok-build-supervisor MCP tools as a guarded transport. A user-level daemon owns a separate Leader, ACP connection, visible TUI records, and event journal for each workspace, independently of any one host task. Workspaces share the initialized proxy settings. Each task gets a thin authenticated MCP client. Keep transport diagnostics internal during normal work and report only ready, working, needs permission, needs input, completed, or failed.

User-facing messages

• Render user-facing explanations in this order: an explicit language request, otherwise the language of the user's latest substantive message/current task, otherwise a genuinely known host or OS locale, otherwise English. Never persist an inferred language. Keep JSON keys, states, enum values, tool names, permission/form option values, paths, commands, hashes, task/session/agent IDs, and error/status codes verbatim.
• Keep preflight silent. Tool availability, tool counts or names, Supervisor reachability, ACP/Leader state, the working directory, and presentation details are internal unless they block the request or the user explicitly asks for diagnostics.
• Do not ask the user to create, open, show, resume, or select a TUI as a separate step. /grok_execute on owns workspace selection and session setup. If startup takes long enough to merit an update, give only a short localized statement that Grok is connecting.
• For /grok_execute on, return one concise standalone result after the visible TUI is ready: executor mode is on, the terminal is ready, and the user can provide the task. The one attention-state exception is needs_workspace_trust: explain that Grok is waiting for the user's trust decision in the already-open terminal and that /grok_execute on must not be run again. Render either message using the language rule above. Keep executor mode pending, then inspect the same session again after the user decides. For ordinary task dispatch, report the task state or outcome instead of narrating TUI lifecycle details.
• Do not volunteer that no development prompt was sent. Mention that boundary only when the user explicitly asked to open a session without sending work or could otherwise reasonably mistake connection setup for submitting a task.
• For blocked or failed states, report only the actionable cause and next step; expose transport diagnostics only on request.

Workflow

Host entry normalization: use Grok Executor Policy for explicit native skill and namespaced command entry points. Every exact /grok_execute on or /grok_execute off below also means its normalized explicit invocation, including after host command expansion. This never authorizes activation from ordinary task text or implicit skill selection. For initialization, an explicit Codex $grok-build-supervisor init (optionally followed by one loopback HTTP URL) or Claude Code /grok-build-supervisor:grok_init with the same optional URL is equivalent to /grok_init; reject extra arguments. Bare skill selection is not initialization.

/grok_execute off disables new Grok opens, resumes, and prompts for this host task without cancelling existing work or closing the TUI. Read-only inspection remains allowed. After off, only an exact /grok_execute on reactivates execution; ordinary “continue”, “resume the task”, “继续”, or “直接开始刚才的任务吧” does not. Current or recovered task authorization does not substitute for this explicit activation switch.

1. Call grok_init only for an exact /grok_init command or an explicit request to initialize or reinitialize the Grok Supervisor proxy. Empty initialization performs bounded local discovery; an exact loopback http:// URL verifies that selection. Initialization never opens a session or sends work. Do not initialize implicitly during ordinary preflight. If more than one verified endpoint is returned, show the bounded candidates and require an exact user choice. A listening port alone is not success: require the persisted ready result backed by HTTP CONNECT verification. Reinitialization is refused while the Supervisor owns active work.
2. Call grok_session_inspect with its default interaction view and the current host task's absolute project cwd. Keep that cwd on subsequent calls, together with the exact session/run IDs when known. The cwd selects that workspace's connection and journal; another project's terminal being open is not a reason to disconnect it or request /grok_execute off. Interaction intentionally omits process, socket, journal, and ownership diagnostics. When the user names a prior task naturally, use the explicit summary view with the absolute project cwd and a short sessionQuery; use a candidate only when it is unique.
3. Select the session mode internally without constructing shell text or asking the user to manage the TUI:

• During an exact /grok_execute on, bind the current host task's absolute project directory. If no session is attached, use mode: new with no sessionId; if one exact attached session already belongs to that directory, use mode: resume with its UUID.
• A missing, relative, or ambiguous host workspace leaves executor mode off. Never substitute the plugin process directory or a workspace remembered by another task.
• For later task dispatch, reuse the session already ensured by on rather than waiting for the first development task to open it.
• Ask the user to choose only when recovery produces multiple genuinely ambiguous candidates; ordinary startup and reuse require no separate user instruction.

1. Call grok_session_open during /grok_execute on with the bound absolute project directory and explicit confirmation. Always use the default presentation: windows_terminal, which opens a dedicated Windows Terminal PowerShell tab, unless the user explicitly requested headless, invisible, or ACP-only operation before activation. Only that explicit request permits presentation: none with OPEN_GROK_SESSION_HEADLESS; never select it as a convenience, fallback, or preflight optimization. Visible sessions use OPEN_GROK_SESSION. The daemon attempts to roll back only its owned processes on failure. An error response is not proof that rollback completed: preserve the exact error, details.rollback, and details.rollbackComplete, then use explicit diagnostic views before reporting the outcome. It may recover an active TUI only when the exact session, cwd, PID, dedicated Leader, and Supervisor launch record all match; an unrelated TUI is never adopted. Do not mark executor mode active until this step succeeds.

• If opening reports GROK_PROXY_NOT_INITIALIZED, tell the user to run /grok_init; do not copy a host environment port into the request or silently initialize it.
• If routing reports GROK_WORKSPACE_REQUIRED, supply the already-known current workspace cwd. For GROK_WORKSPACE_SESSION_MISMATCH, re-inspect that exact cwd and verify the session rather than switching another project's connection. A daemon that predates multiWorkspaceSessions must become idle before upgrading; preserve its existing work and report that upgrade boundary.
• If opening reports needs_workspace_trust, this is Grok's native directory-trust gate, not an ordinary ACP tool permission. The structured request includes the exact session, cwd, canonical workspace, and detected local-config kinds. Keep the same TUI and ACP attachment, do not call open again, and do not use grok_session_respond. Ask the user to choose in the visible Grok terminal. The Supervisor answers Grok's ACP trust round-trip only after that owned TUI registers the session, which proves the native screen was passed.
• awaiting_session_registration is the bounded compatibility fallback when a visible owned TUI has not registered but no structured trust request was received. Say the terminal is still starting and ask the user to check it; do not claim that it is definitely a trust screen and do not open another TUI.

1. Opening a TUI does not authorize a prompt. Call grok_session_prompt only when the user has authorized the actual instruction.

• Host identity is supplied by the MCP frontend and authenticated daemon envelope, not by a model-visible tool argument. Do not add or invent a host label in the prompt: the Supervisor renders the Codex, Claude Code, Pi, or neutral host-agent supervision contract from the actual sender.
• Preserve the user's task language in the execution brief and ask Grok to use that language for narrative progress and the final result unless the user explicitly requests another language. Do not translate machine tokens or exact options.

1. After grok_session_prompt returns, keep the current host turn alive until it reaches an attention or terminal state:

• Call grok_session_inspect with view: interaction, the bound cwd, the exact sessionId and runId, the returned nextAfterSequence, and waitMs: 25000. Cursors belong to that workspace's journal; never reuse one across workspaces.
• Replace afterSequence with every returned cursor.nextAfterSequence before the next call. Never poll again with a stale cursor: operational interaction polls intentionally coalesce all routine stream events up to latestSequence.
• While state is working or cancelling, use only the compact state and progress metadata. progress.phase is the current bounded stage; responseChars counts agent text observed without returning it; lastChunkAt advances only when agent text arrives; heartbeatAt is the latest liveness evaluation; and newActivity means journal activity exists beyond the cursor supplied by this caller. It does not by itself prove useful semantic progress. Streamed agent message bodies are suppressed until a terminal result, so do not try to reconstruct the answer from polling updates. A bounded wait timeout is not completion.
• Quiet telemetry alone is neither failure nor a reason to ask the user to reauthorize waiting. If repeated waits leave a material liveness question, inspect the exact run's focused diagnostics and continue its authorized work while it remains active; report a confirmed failure, required user action, or unresolved recovery boundary. Never cancel automatically from quiet telemetry alone.
• For needs_permission, explain the request using the user-facing language rule, present the exact returned options without translation, and wait for the user's choice. Use grok_session_respond with the bound cwd, exact session and permission IDs, and ANSWER_GROK_PERMISSION, then resume the same wait loop.
• For native needs_input, inspect the returned ACP form question. The host agent may answer directly only from verified context already inside its authority; route it to the user when owner authority, a consequential choice, or missing facts are required. Never invent values. Use grok_session_respond with ANSWER_GROK_INPUT, then resume the same wait loop.
• If needs_input has source: fallback, Grok ended the turn with a structured question because ACP elicitation was unavailable. Ask the user, then send the answer as a new authorized prompt in the same session.
• For completed, consume run.finalText only when delivery.finalTextIncluded is true. When delivery.resultArtifactIncluded is true, use run.resultArtifact instead: it contains an absolute persistent path, byte size, SHA-256, media type, captured/source character counts, truncation flag, and bounded summary. Multiple ACP messageId values are preserved as one ordered result before this inline-versus-artifact decision, and run.messageCount reports how many messages were captured. Retain the returned cursor and stop polling that completed run; a later call with the advanced cursor returns availability metadata without repeating either payload. Preserve an artifact's original la