@gcszhn/mcp-sentinel-opencode-plugin

An OpenCode plugin that acts as a sentinel between the AI agent and MCP servers — polling long-running tasks on the agent's behalf so that token-costly status loops never enter the LLM inference path.

This package is the OpenCode harness adapter for @gcszhn/mcp-sentinel-core.

Install

opencode plugin -g @gcszhn/mcp-sentinel-opencode-plugin

Or add it to your opencode.jsonc (project .opencode/opencode.jsonc or global ~/.config/opencode/opencode.jsonc):

{
  "plugin": ["@gcszhn/mcp-sentinel-opencode-plugin"],
}

The plugin reads your existing MCP server config — no additional setup needed.

Tools

mcp_sentinel_poll

Submit a long-running MCP tool call and poll it at regular intervals until a condition is met. Returns a sentinel ID immediately; the agent is notified via promptAsync when done.

Parameter	Type	Default	Description
server	string	required	MCP server name (from opencode config)
tool	string	required	Tool name to call on the server
args	object	{}	JSON object of arguments for the tool
interval	number	5000	Poll interval in milliseconds
timeout	number	optional	Max poll duration in ms (unset = no limit)
until	object	required	JSON condition object

mcp_sentinel_status

Check status, list active tasks, or cancel a running task (action = status | list | cancel).

mcp_sentinel_attach

Block the agent, waiting for a sentinel to complete. Zero token cost during the wait.

mcp_sentinel_read

Read raw poll outputs with offset/limit pagination.

Condition model

Conditions are pure declarative data:

{ "path": "status", "is": "eq", "value": "completed" }
{ "and": [
  { "path": "status", "is": "eq", "value": "completed" },
  { "path": "tasks[0].exit_code", "is": "eq", "value": 0 }
] }

See the repository root README.md for the full operator and path syntax.

Environment variables

Variable	Default	Description
SENTINEL_MAX_POLL_LOG	unlimited	Max poll log entries per task (FIFO trim)
SENTINEL_TASK_TTL_MS	unlimited	Auto-cleanup completed tasks after N ms

License

MIT