@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