@gcszhn/mcp-sentinel-opencode2-plugin 0.0.0-stage → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mcp-sentinel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @gcszhn/mcp-sentinel-opencode2-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [OpenCode 2](https://opencode.ai) (**V2**) 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 2 harness adapter for `@gcszhn/mcp-sentinel-core`.
+It uses the V2 plugin API (`Plugin.define` / `ctx.tool.transform` /
+`ctx.mcp.transform` / `ctx.session.synthetic`) and is independent from the V1
+`@gcszhn/mcp-sentinel-opencode-plugin`.
+
+## Install
+
+Add the plugin to your OpenCode 2 config (`opencode.jsonc`):
+
+```jsonc
+{
+  "plugins": ["@gcszhn/mcp-sentinel-opencode2-plugin"],
+}
+```
+
+The plugin discovers the MCP servers already configured under `mcp.servers` in
+your OpenCode config and opens its own connections to them. **No sentinel-specific
+MCP configuration is required.**
+
+Why its own connections: the V2 plugin SDK (`@opencode/plugin` 2.3.0) has no API
+for invoking a host MCP tool. `ctx.mcp` only exposes `list` / `transform` /
+`reload` (server config and status), and the host client's `mcp.*` API is
+limited to `list`, `resource.catalog`, `add`, `remove`, `connect`, `disconnect`,
+and `client.token`. `ctx.tool` can register and inspect plugin tools, and hooks
+can observe agent tool calls, but nothing can execute a host MCP tool
+programmatically. The adapter therefore runs in connection-pool mode: it reads
+the server config from the host and lets the shared core own the MCP client.
+
+Unlike V1, V2 config declares servers under `mcp.servers.{name}`:
+
+```jsonc
+{
+  "mcp": {
+    "servers": {
+      "my-server": {
+        "type": "local",
+        "command": ["bun", "run", "./server.ts"],
+      },
+    },
+  },
+}
+```
+
+## 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 in
+its session when the sentinel resolves.
+
+| Parameter  | Type   | Default    | Description                                |
+| ---------- | ------ | ---------- | ------------------------------------------ |
+| `server`   | string | _required_ | MCP server name (from `mcp.servers`)       |
+| `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:
+
+```jsonc
+{ "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.
+
+## Options
+
+Options are read from the plugin entry in V2 config:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@gcszhn/mcp-sentinel-opencode2-plugin",
+      "options": { "delivery": "queue", "resume": true },
+    },
+  ],
+}
+```
+
+| Option     | Type      | Default   | Description                                                           |
+| ---------- | --------- | --------- | --------------------------------------------------------------------- |
+| `delivery` | `string`  | `"queue"` | How completion notices enter the session: `"queue"` or `"steer"`.     |
+| `resume`   | `boolean` | `true`    | Whether a completion notice resumes a session that is currently idle. |
+
+Notifications are delivered with `ctx.session.synthetic`, so they appear as a
+background system notice rather than a user prompt.
+
+## OAuth limitation
+
+The sentinel opens its **own** MCP connection using the connection details in
+`mcp.servers`, so it cannot reuse credentials that OpenCode obtained through an
+interactive OAuth flow. If a remote server is reported as `needs_auth` and has
+no static `headers`, `mcp_sentinel_poll` returns an explicit error explaining
+that static headers must be configured instead of failing later with an opaque 401.
+
+## 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

package/dist/config.d.ts

@@ -0,0 +1,93 @@
+/**
+ * OpenCode 2 (V2) harness — MCP config discovery and preflight checks.
+ *
+ * In V2 the host exposes MCP configuration through the `ctx.mcp` domain. The
+ * plugin captures the current server list from a synchronous `transform`
+ * callback (the only place V2 exposes `editor.list()`), then normalizes that
+ * V2 shape into the core's {@link McpConfig} for connection-pool mode:
+ *
+ * ```jsonc
+ * {
+ *   "mcp": {
+ *     "servers": {
+ *       "name": {
+ *         "type": "local",
+ *         "command": ["bun", "run", "server.ts"],
+ *         "environment": { "KEY": "value" },
+ *         "disabled": false
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Differences from V1:
+ * - servers live under `mcp.servers.{name}` (not flat `mcp.{name}`)
+ * - `environment` replaces `env`
+ * - `disabled` is the inverse of V1's `enabled`
+ *
+ * @module
+ */
+import type { McpConfig } from "@gcszhn/mcp-sentinel-core";
+/**
+ * Minimal structural view of a V2 `Mcp.ServerConfig`.
+ *
+ * Kept intentionally loose (and free of `@opencode/plugin`/`effect` types) so
+ * this module is testable in isolation and stays tolerant of schema additions.
+ */
+export interface Opencode2McpServerConfig {
+    readonly type?: string;
+    readonly command?: unknown;
+    readonly cwd?: unknown;
+    readonly environment?: unknown;
+    readonly disabled?: unknown;
+    readonly url?: unknown;
+    readonly headers?: unknown;
+    readonly oauth?: unknown;
+}
+/** One `[name, config]` entry as returned by the V2 MCP editor. */
+export type Opencode2McpEntry = readonly [string, Opencode2McpServerConfig];
+/** MCP connection status as reported by `ctx.mcp.list()`. */
+export interface Opencode2McpStatus {
+    readonly status: string;
+    readonly error?: string;
+}
+/**
+ * Normalize the V2 MCP server list into the core's {@link McpConfig}.
+ *
+ * Invalid entries (missing/non-string `command`, empty `url`, …) are skipped,
+ * matching the core's contract that only usable server configs reach the
+ * resolver. Disabled servers are kept but marked `enabled: false`, so the
+ * core's {@link makeServerResolver} excludes them consistently.
+ *
+ * @param entries - `[name, config]` entries captured from `ctx.mcp.transform`.
+ * @returns A typed config with a null-prototype `servers` map.
+ */
+export declare function normalizeOpencode2McpConfig(entries: Iterable<Opencode2McpEntry> | null | undefined): McpConfig;
+/**
+ * Look up a raw V2 entry by server name.
+ *
+ * Iterates instead of indexing a map so names such as `__proto__` cannot read
+ * inherited properties.
+ */
+export declare function findMcpEntry(entries: Iterable<Opencode2McpEntry> | null | undefined, name: string): Opencode2McpEntry | undefined;
+/** Whether a remote server declares OAuth authentication (`oauth` other than `false`). */
+export declare function serverUsesOAuth(entry: Opencode2McpEntry | undefined): boolean;
+/** Whether a remote server has non-empty static headers the sentinel can reuse. */
+export declare function serverHasHeaders(entry: Opencode2McpEntry | undefined): boolean;
+/**
+ * Preflight a poll target and return a clean `"Error: ..."` string when the
+ * server cannot be used, or `undefined` when it can.
+ *
+ * V2's MCP config is the source of truth for connection details, while the
+ * host's connection status is the source of truth for authentication. The
+ * sentinel opens its own MCP connection, so it cannot inherit host OAuth
+ * credentials — a `needs_auth` server without static headers is reported
+ * explicitly instead of failing later with an opaque 401.
+ *
+ * @param entries - Captured V2 MCP entries.
+ * @param server - Requested server name.
+ * @param status - Optional `ctx.mcp.list()` status for that server.
+ */
+export declare function describeServerProblem(entries: Iterable<Opencode2McpEntry> | null | undefined, server: string, status?: Opencode2McpStatus): string | undefined;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EACV,SAAS,EAIV,MAAM,2BAA2B,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GAAG,SAAS,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAE5E,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,IAAI,GAAG,SAAS,GACtD,SAAS,CAgBX;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,IAAI,GAAG,SAAS,EACvD,IAAI,EAAE,MAAM,GACX,iBAAiB,GAAG,SAAS,CAM/B;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAI7E;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAI9E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,IAAI,GAAG,SAAS,EACvD,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,kBAAkB,GAC1B,MAAM,GAAG,SAAS,CAsBpB"}

package/dist/config.js

@@ -0,0 +1,179 @@
+/**
+ * OpenCode 2 (V2) harness — MCP config discovery and preflight checks.
+ *
+ * In V2 the host exposes MCP configuration through the `ctx.mcp` domain. The
+ * plugin captures the current server list from a synchronous `transform`
+ * callback (the only place V2 exposes `editor.list()`), then normalizes that
+ * V2 shape into the core's {@link McpConfig} for connection-pool mode:
+ *
+ * ```jsonc
+ * {
+ *   "mcp": {
+ *     "servers": {
+ *       "name": {
+ *         "type": "local",
+ *         "command": ["bun", "run", "server.ts"],
+ *         "environment": { "KEY": "value" },
+ *         "disabled": false
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Differences from V1:
+ * - servers live under `mcp.servers.{name}` (not flat `mcp.{name}`)
+ * - `environment` replaces `env`
+ * - `disabled` is the inverse of V1's `enabled`
+ *
+ * @module
+ */
+/**
+ * Normalize the V2 MCP server list into the core's {@link McpConfig}.
+ *
+ * Invalid entries (missing/non-string `command`, empty `url`, …) are skipped,
+ * matching the core's contract that only usable server configs reach the
+ * resolver. Disabled servers are kept but marked `enabled: false`, so the
+ * core's {@link makeServerResolver} excludes them consistently.
+ *
+ * @param entries - `[name, config]` entries captured from `ctx.mcp.transform`.
+ * @returns A typed config with a null-prototype `servers` map.
+ */
+export function normalizeOpencode2McpConfig(entries) {
+    // Null-prototype map so a server literally named `__proto__` cannot mutate
+    // the object's prototype.
+    const servers = Object.create(null);
+    if (!entries)
+        return { servers };
+    for (const entry of entries) {
+        if (!Array.isArray(entry) || entry.length < 2)
+            continue;
+        const [name, raw] = entry;
+        if (typeof name !== "string" || !isRecord(raw))
+            continue;
+        const normalized = normalizeServerEntry(raw);
+        if (normalized)
+            servers[name] = normalized;
+    }
+    return { servers };
+}
+/**
+ * Look up a raw V2 entry by server name.
+ *
+ * Iterates instead of indexing a map so names such as `__proto__` cannot read
+ * inherited properties.
+ */
+export function findMcpEntry(entries, name) {
+    if (!entries)
+        return undefined;
+    for (const entry of entries) {
+        if (Array.isArray(entry) && entry.length >= 2 && entry[0] === name)
+            return entry;
+    }
+    return undefined;
+}
+/** Whether a remote server declares OAuth authentication (`oauth` other than `false`). */
+export function serverUsesOAuth(entry) {
+    if (!entry)
+        return false;
+    const raw = entry[1];
+    return raw.type === "remote" && raw.oauth !== undefined && raw.oauth !== false;
+}
+/** Whether a remote server has non-empty static headers the sentinel can reuse. */
+export function serverHasHeaders(entry) {
+    if (!entry)
+        return false;
+    const headers = entry[1].headers;
+    return isRecord(headers) && Object.keys(headers).length > 0;
+}
+/**
+ * Preflight a poll target and return a clean `"Error: ..."` string when the
+ * server cannot be used, or `undefined` when it can.
+ *
+ * V2's MCP config is the source of truth for connection details, while the
+ * host's connection status is the source of truth for authentication. The
+ * sentinel opens its own MCP connection, so it cannot inherit host OAuth
+ * credentials — a `needs_auth` server without static headers is reported
+ * explicitly instead of failing later with an opaque 401.
+ *
+ * @param entries - Captured V2 MCP entries.
+ * @param server - Requested server name.
+ * @param status - Optional `ctx.mcp.list()` status for that server.
+ */
+export function describeServerProblem(entries, server, status) {
+    // Empty names are reported by the core handler with its canonical message.
+    if (!server.trim())
+        return undefined;
+    const entry = findMcpEntry(entries, server);
+    if (!entry)
+        return `Error: Unknown MCP server: ${server}`;
+    const raw = entry[1];
+    if (raw.disabled === true) {
+        return `Error: MCP server "${server}" is disabled in OpenCode configuration.`;
+    }
+    const normalized = normalizeOpencode2McpConfig(entries);
+    if (!Object.hasOwn(normalized.servers, server)) {
+        return `Error: MCP server "${server}" has an unsupported configuration (expected a local command array or a remote url).`;
+    }
+    if (status?.status === "needs_auth" && !serverHasHeaders(entry)) {
+        return `Error: MCP server "${server}" requires OAuth authentication. mcp-sentinel opens its own MCP connection and cannot reuse OpenCode's OAuth credentials; configure static headers for this server instead.${status.error ? ` (${status.error})` : ""}`;
+    }
+    return undefined;
+}
+/** Normalize one raw V2 server entry, or `null` when it is not usable. */
+function normalizeServerEntry(raw) {
+    const disabled = raw.disabled === true;
+    if (raw.type === "local") {
+        const command = normalizeCommand(raw.command);
+        if (!command)
+            return null;
+        const local = {
+            type: "local",
+            command,
+            enabled: !disabled,
+        };
+        if (typeof raw.cwd === "string")
+            local.cwd = raw.cwd;
+        const env = normalizeStringMap(raw.environment);
+        if (env)
+            local.env = env;
+        return local;
+    }
+    if (raw.type === "remote") {
+        if (typeof raw.url !== "string" || raw.url.trim() === "")
+            return null;
+        const remote = {
+            type: "remote",
+            url: raw.url,
+            enabled: !disabled,
+        };
+        const headers = normalizeStringMap(raw.headers);
+        if (headers)
+            remote.headers = headers;
+        return remote;
+    }
+    return null;
+}
+/** Accept only a non-empty array of stringifiable command parts. */
+function normalizeCommand(command) {
+    if (!Array.isArray(command) || command.length === 0)
+        return null;
+    if (!command.every((part) => typeof part === "string"))
+        return null;
+    return command.map((part) => part);
+}
+/** Normalize a `Record<string, string>`-shaped value, or `undefined` when absent. */
+function normalizeStringMap(value) {
+    if (!isRecord(value))
+        return undefined;
+    const result = Object.create(null);
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === "string")
+            result[key] = entry;
+    }
+    return result;
+}
+/** Whether `value` is a non-null, non-array object. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/host-registry.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OpenCode 2 (V2) harness — host binding registry.
+ *
+ * The core keeps its notifier and log sink in module-level state. V2 can load
+ * one plugin instance per location **in the same server process**, and all of
+ * those instances import the same core module. A naive
+ * `setNotifier(instanceNotifier)` would let the last-loaded instance clobber
+ * the others, and a per-instance `cleanup()` would wipe every location's
+ * tasks.
+ *
+ * This registry keeps each instance's channels and routes notifications by the
+ * session that started the sentinel (`task.request.sessionID`), falling back to
+ * the most recently registered instance when no owner is known. Global core
+ * cleanup is the caller's job and must only run when the registry is empty.
+ *
+ * @module
+ */
+import type { LogSink, SentinelEvent, SentinelNotifier, SentinelTask } from "@gcszhn/mcp-sentinel-core";
+/** A single plugin instance's notification and logging channels. */
+export interface HostBinding {
+    /** Delivers a resolved sentinel to this instance's host session channel. */
+    readonly notifier: SentinelNotifier;
+    /** Writes a structured log entry through this instance's host log channel. */
+    readonly logSink: LogSink;
+}
+/** Return the most recently registered binding, if any. */
+export declare function getActiveHostBinding(): HostBinding | undefined;
+/** Number of currently registered plugin instances. */
+export declare function getHostBindingCount(): number;
+/**
+ * Record which plugin instance owns a session, so that session's sentinel
+ * completions are delivered through the same instance's `ctx.session`.
+ */
+export declare function claimSession(sessionID: string | undefined, binding: HostBinding): void;
+/**
+ * Dispatch a sentinel resolution to the binding that owns the task's session.
+ *
+ * Falls back to the most recently registered binding for tasks without an
+ * owner (for example, tasks recovered after a plugin reload). Exported so the
+ * routing behavior can be unit-tested directly.
+ */
+export declare function dispatchNotification(task: SentinelTask, event: SentinelEvent): Promise<void>;
+/**
+ * Register a plugin instance's channels and install the shared dispatchers.
+ *
+ * Idempotent for the same binding object.
+ */
+export declare function registerHostBinding(binding: HostBinding): void;
+/**
+ * Remove a plugin instance's channels.
+ *
+ * When the last instance unloads, the core notifier/log sink are cleared and
+ * all session ownership is forgotten. The caller decides whether to run the
+ * core's global `cleanup()`/`disconnectAll()`; see `src/index.ts`.
+ */
+export declare function unregisterHostBinding(binding: HostBinding): void;
+//# sourceMappingURL=host-registry.d.ts.map

package/dist/host-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-registry.d.ts","sourceRoot":"","sources":["../src/host-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,gBAAgB,EAChB,YAAY,EACb,MAAM,2BAA2B,CAAC;AAEnC,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAKD,2DAA2D;AAC3D,wBAAgB,oBAAoB,IAAI,WAAW,GAAG,SAAS,CAE9D;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAEtF;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CAKf;AAQD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAI9D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAahE"}

package/dist/host-registry.js

@@ -0,0 +1,88 @@
+/**
+ * OpenCode 2 (V2) harness — host binding registry.
+ *
+ * The core keeps its notifier and log sink in module-level state. V2 can load
+ * one plugin instance per location **in the same server process**, and all of
+ * those instances import the same core module. A naive
+ * `setNotifier(instanceNotifier)` would let the last-loaded instance clobber
+ * the others, and a per-instance `cleanup()` would wipe every location's
+ * tasks.
+ *
+ * This registry keeps each instance's channels and routes notifications by the
+ * session that started the sentinel (`task.request.sessionID`), falling back to
+ * the most recently registered instance when no owner is known. Global core
+ * cleanup is the caller's job and must only run when the registry is empty.
+ *
+ * @module
+ */
+import { setLogSink, setNotifier } from "@gcszhn/mcp-sentinel-core";
+const bindings = [];
+const sessionOwners = new Map();
+/** Return the most recently registered binding, if any. */
+export function getActiveHostBinding() {
+    return bindings[bindings.length - 1];
+}
+/** Number of currently registered plugin instances. */
+export function getHostBindingCount() {
+    return bindings.length;
+}
+/**
+ * Record which plugin instance owns a session, so that session's sentinel
+ * completions are delivered through the same instance's `ctx.session`.
+ */
+export function claimSession(sessionID, binding) {
+    if (sessionID)
+        sessionOwners.set(sessionID, binding);
+}
+/**
+ * Dispatch a sentinel resolution to the binding that owns the task's session.
+ *
+ * Falls back to the most recently registered binding for tasks without an
+ * owner (for example, tasks recovered after a plugin reload). Exported so the
+ * routing behavior can be unit-tested directly.
+ */
+export async function dispatchNotification(task, event) {
+    const sessionID = task.request.sessionID;
+    const owner = sessionID ? sessionOwners.get(sessionID) : undefined;
+    const binding = owner && bindings.includes(owner) ? owner : getActiveHostBinding();
+    if (binding)
+        await binding.notifier(task, event);
+}
+/** Route a core log entry to the active plugin instance's host log channel. */
+const dispatchLog = (level, message, extra) => {
+    const binding = getActiveHostBinding();
+    if (binding)
+        return binding.logSink(level, message, extra);
+};
+/**
+ * Register a plugin instance's channels and install the shared dispatchers.
+ *
+ * Idempotent for the same binding object.
+ */
+export function registerHostBinding(binding) {
+    if (!bindings.includes(binding))
+        bindings.push(binding);
+    setNotifier(dispatchNotification);
+    setLogSink(dispatchLog);
+}
+/**
+ * Remove a plugin instance's channels.
+ *
+ * When the last instance unloads, the core notifier/log sink are cleared and
+ * all session ownership is forgotten. The caller decides whether to run the
+ * core's global `cleanup()`/`disconnectAll()`; see `src/index.ts`.
+ */
+export function unregisterHostBinding(binding) {
+    const index = bindings.indexOf(binding);
+    if (index !== -1)
+        bindings.splice(index, 1);
+    for (const [sessionID, owner] of sessionOwners) {
+        if (owner === binding)
+            sessionOwners.delete(sessionID);
+    }
+    if (bindings.length === 0) {
+        setNotifier(null);
+        setLogSink(null);
+        sessionOwners.clear();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OpenCode 2 (V2) adapter — registers the four sentinel tools through the V2
+ * `Plugin.define` / `ctx.tool.transform` API and wires OpenCode-specific
+ * integration (MCP config discovery, synthetic session notifications, console
+ * logging) into the framework-agnostic core.
+ *
+ * All request/response logic lives in `@gcszhn/mcp-sentinel-core/tools`; this
+ * file owns only the V2 seams:
+ * - `ctx.mcp.transform(editor => editor.list())` for MCP config discovery
+ * - `ctx.tool.transform(editor => editor.add(...))` for JSON-Schema tools
+ * - `context.sessionID` / `context.signal` for task ownership and abort
+ * - `ctx.session.synthetic()` for completion delivery
+ * - a cleanup function returned from `setup` for resource release
+ *
+ * @module
+ */
+import { Plugin } from "@opencode/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;;AAiK1C,wBAoNG"}

package/dist/index.js

@@ -0,0 +1,300 @@
+/**
+ * OpenCode 2 (V2) adapter — registers the four sentinel tools through the V2
+ * `Plugin.define` / `ctx.tool.transform` API and wires OpenCode-specific
+ * integration (MCP config discovery, synthetic session notifications, console
+ * logging) into the framework-agnostic core.
+ *
+ * All request/response logic lives in `@gcszhn/mcp-sentinel-core/tools`; this
+ * file owns only the V2 seams:
+ * - `ctx.mcp.transform(editor => editor.list())` for MCP config discovery
+ * - `ctx.tool.transform(editor => editor.add(...))` for JSON-Schema tools
+ * - `context.sessionID` / `context.signal` for task ownership and abort
+ * - `ctx.session.synthetic()` for completion delivery
+ * - a cleanup function returned from `setup` for resource release
+ *
+ * @module
+ */
+import { Plugin } from "@opencode/plugin";
+import { ACTION_DESCRIPTION, ARGS_DESCRIPTION, ATTACH_ID_DESCRIPTION, ATTACH_TIMEOUT_DESCRIPTION, ATTACH_TOOL_DESCRIPTION, COMPLETION_NOTIFICATION_NOTE, INTERVAL_DESCRIPTION, POLL_TIMEOUT_DESCRIPTION, POLL_TOOL_DESCRIPTION, READ_ID_DESCRIPTION, READ_LIMIT_DESCRIPTION, READ_OFFSET_DESCRIPTION, READ_TOOL_DESCRIPTION, SERVER_DESCRIPTION, STATUS_ID_DESCRIPTION, STATUS_TOOL_DESCRIPTION, TOOL_DESCRIPTION, UNTIL_DESCRIPTION, cleanup, disconnectAll, handleAttach, handlePoll, handleRead, handleStatus, logError, logInfo, logWarn, makeConnectionInvoker, makeServerResolver, } from "@gcszhn/mcp-sentinel-core";
+import { describeServerProblem, normalizeOpencode2McpConfig } from "./config.js";
+import { claimSession, getHostBindingCount, registerHostBinding, unregisterHostBinding, } from "./host-registry.js";
+import { buildNotificationText } from "./notify.js";
+/** Stable plugin identifier used by OpenCode diagnostics and plugin storage. */
+const PLUGIN_ID = "mcp-sentinel-opencode2";
+function parsePollInput(raw) {
+    if (!isRecord(raw))
+        return "Error: invalid poll input; expected a JSON object.";
+    if (typeof raw.server !== "string")
+        return "Error: server must be a string.";
+    if (typeof raw.tool !== "string")
+        return "Error: tool must be a string.";
+    if (raw.args !== undefined && !isRecord(raw.args)) {
+        return "Error: args must be a JSON object.";
+    }
+    if (!isNonNegativeInteger(raw.interval)) {
+        return "Error: interval must be a non-negative integer.";
+    }
+    if (!isNonNegativeInteger(raw.timeout)) {
+        return "Error: timeout must be a non-negative integer.";
+    }
+    if (!isRecord(raw.until)) {
+        return "Error: until must be a JSON object describing a condition.";
+    }
+    return {
+        server: raw.server,
+        tool: raw.tool,
+        args: raw.args ?? {},
+        interval: raw.interval,
+        timeout: raw.timeout,
+        until: raw.until,
+    };
+}
+function parseStatusInput(raw) {
+    if (!isRecord(raw))
+        return "Error: invalid status input; expected a JSON object.";
+    if (raw.action !== undefined && typeof raw.action !== "string") {
+        return "Error: action must be a string.";
+    }
+    if (raw.id !== undefined && typeof raw.id !== "string") {
+        return "Error: id must be a string.";
+    }
+    return { action: raw.action, id: raw.id };
+}
+function parseAttachInput(raw) {
+    if (!isRecord(raw))
+        return "Error: invalid attach input; expected a JSON object.";
+    if (typeof raw.id !== "string" || raw.id.trim() === "") {
+        return "Error: id must be a non-empty string.";
+    }
+    if (!isNonNegativeInteger(raw.timeout)) {
+        return "Error: timeout must be a non-negative integer.";
+    }
+    return { id: raw.id, timeout: raw.timeout };
+}
+function parseReadInput(raw) {
+    if (!isRecord(raw))
+        return "Error: invalid read input; expected a JSON object.";
+    if (typeof raw.id !== "string" || raw.id.trim() === "") {
+        return "Error: id must be a non-empty string.";
+    }
+    if (!isNonNegativeInteger(raw.offset)) {
+        return "Error: offset must be a non-negative integer.";
+    }
+    if (!isNonNegativeInteger(raw.limit) || (raw.limit !== undefined && raw.limit < 1)) {
+        return "Error: limit must be a positive integer.";
+    }
+    return { id: raw.id, offset: raw.offset, limit: raw.limit };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonNegativeInteger(value) {
+    return (value === undefined || (typeof value === "number" && Number.isInteger(value) && value >= 0));
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+export default Plugin.define({
+    id: PLUGIN_ID,
+    async setup(ctx) {
+        // V2 exposes MCP *configuration* only inside a transform; `ctx.mcp.list()`
+        // returns connection status, not config. Capture the current entries from
+        // this cheap, synchronous, replayable callback. OpenCode replays it when
+        // the registry is rebuilt (for example after a config reload).
+        let mcpEntries = [];
+        await ctx.mcp.transform((editor) => {
+            mcpEntries = editor.list();
+        });
+        const delivery = ctx.options.delivery === "steer" ? "steer" : "queue";
+        const resume = ctx.options.resume !== false;
+        const logSink = (level, message, extra) => {
+            const line = `[mcp-sentinel] ${message}`;
+            const details = extra && Object.keys(extra).length > 0 ? extra : undefined;
+            switch (level) {
+                case "debug":
+                    console.debug(line, details ?? "");
+                    break;
+                case "info":
+                    console.log(line, details ?? "");
+                    break;
+                case "warn":
+                    console.warn(line, details ?? "");
+                    break;
+                case "error":
+                    console.error(line, details ?? "");
+                    break;
+                default:
+                    console.log(line, details ?? "");
+                    break;
+            }
+        };
+        const notifier = async (task, event) => {
+            const sessionID = task.request.sessionID;
+            if (!sessionID)
+                return;
+            try {
+                // Synthetic messages are background system notices, not user prompts:
+                // they bypass the prompt-admission hook and resume the session by
+                // default. `queue` avoids reordering work the user is already doing.
+                const synthetic = {
+                    sessionID,
+                    text: buildNotificationText(task, event),
+                    description: "MCP Sentinel result",
+                    delivery,
+                    resume,
+                };
+                await ctx.session.synthetic(synthetic);
+            }
+            catch (err) {
+                // The task remains queryable via status/read; log the delivery failure
+                // so it can be diagnosed instead of disappearing silently.
+                logError("Failed to deliver sentinel notification", {
+                    id: task.id,
+                    sessionID,
+                    error: String(err),
+                });
+                throw err;
+            }
+        };
+        const binding = { notifier, logSink };
+        registerHostBinding(binding);
+        logInfo("MCP Sentinel OpenCode 2 plugin initialized", { version: ctx.app.version });
+        /** Read a server's connection status from the host's MCP domain. */
+        const getMcpStatus = async (name) => {
+            const listed = await ctx.mcp.list();
+            const found = listed.data.find((server) => server.name === name);
+            if (!found)
+                return undefined;
+            const status = found.status;
+            if (status.status === "failed" || status.status === "needs_auth") {
+                return { status: status.status, error: status.error };
+            }
+            return { status: status.status };
+        };
+        await ctx.tool.transform((editor) => {
+            editor.add({
+                name: "mcp_sentinel_poll",
+                description: `${POLL_TOOL_DESCRIPTION}
+
+${COMPLETION_NOTIFICATION_NOTE}`,
+                input: {
+                    type: "object",
+                    properties: {
+                        server: { type: "string", description: SERVER_DESCRIPTION },
+                        tool: { type: "string", description: TOOL_DESCRIPTION },
+                        args: { type: "object", description: ARGS_DESCRIPTION, additionalProperties: true },
+                        interval: { type: "integer", minimum: 1000, description: INTERVAL_DESCRIPTION },
+                        timeout: { type: "integer", minimum: 0, description: POLL_TIMEOUT_DESCRIPTION },
+                        until: { type: "object", description: UNTIL_DESCRIPTION, additionalProperties: true },
+                    },
+                    required: ["server", "tool", "until"],
+                    additionalProperties: false,
+                },
+                async execute(raw, context) {
+                    const input = parsePollInput(raw);
+                    if (typeof input === "string")
+                        return { content: input };
+                    // Snapshot the captured config for this call so a replay during the
+                    // poll cannot split resolution and invocation across versions.
+                    const entries = mcpEntries;
+                    let status;
+                    if (input.server.trim()) {
+                        try {
+                            status = await getMcpStatus(input.server);
+                        }
+                        catch (err) {
+                            // Status is only a preflight aid. The sentinel opens its own
+                            // connection, so proceed if the status lookup itself fails.
+                            logWarn("Could not read MCP status before polling", {
+                                server: input.server,
+                                error: String(err),
+                            });
+                        }
+                    }
+                    const problem = describeServerProblem(entries, input.server, status);
+                    if (problem)
+                        return { content: problem };
+                    claimSession(context.sessionID, binding);
+                    const content = await handlePoll({
+                        ...input,
+                        sessionID: context.sessionID,
+                    }, makeConnectionInvoker(makeServerResolver(normalizeOpencode2McpConfig(entries))));
+                    return { content };
+                },
+            });
+            editor.add({
+                name: "mcp_sentinel_status",
+                description: STATUS_TOOL_DESCRIPTION,
+                input: {
+                    type: "object",
+                    properties: {
+                        action: {
+                            type: "string",
+                            enum: ["status", "list", "cancel"],
+                            description: ACTION_DESCRIPTION,
+                        },
+                        id: { type: "string", description: STATUS_ID_DESCRIPTION },
+                    },
+                    additionalProperties: false,
+                },
+                async execute(raw) {
+                    const input = parseStatusInput(raw);
+                    if (typeof input === "string")
+                        return { content: input };
+                    return { content: handleStatus(input.action, input.id) };
+                },
+            });
+            editor.add({
+                name: "mcp_sentinel_attach",
+                description: ATTACH_TOOL_DESCRIPTION,
+                input: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: ATTACH_ID_DESCRIPTION },
+                        timeout: { type: "integer", minimum: 0, description: ATTACH_TIMEOUT_DESCRIPTION },
+                    },
+                    required: ["id"],
+                    additionalProperties: false,
+                },
+                async execute(raw, context) {
+                    const input = parseAttachInput(raw);
+                    if (typeof input === "string")
+                        return { content: input };
+                    return {
+                        content: await handleAttach(input.id, input.timeout, () => context.signal.aborted),
+                    };
+                },
+            });
+            editor.add({
+                name: "mcp_sentinel_read",
+                description: READ_TOOL_DESCRIPTION,
+                input: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: READ_ID_DESCRIPTION },
+                        offset: { type: "integer", minimum: 0, description: READ_OFFSET_DESCRIPTION },
+                        limit: { type: "integer", minimum: 1, description: READ_LIMIT_DESCRIPTION },
+                    },
+                    required: ["id"],
+                    additionalProperties: false,
+                },
+                async execute(raw) {
+                    const input = parseReadInput(raw);
+                    if (typeof input === "string")
+                        return { content: input };
+                    return { content: handleRead(input.id, input.offset, input.limit) };
+                },
+            });
+        });
+        // V2 disposes registrations automatically. Release only the process-wide
+        // core resources once the last plugin instance for this server unloads;
+        // otherwise one location would wipe another location's sentinels.
+        return async () => {
+            unregisterHostBinding(binding);
+            if (getHostBindingCount() === 0) {
+                cleanup();
+                await disconnectAll();
+            }
+        };
+    },
+});

package/dist/notify.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OpenCode 2 (V2) harness — completion notification text.
+ *
+ * The message format is host-specific and therefore lives in the adapter, not
+ * in the core. It is delivered through the V2 session inbox as a synthetic
+ * message (see `src/index.ts`), not as a user prompt.
+ *
+ * @module
+ */
+import type { SentinelEvent, SentinelTask } from "@gcszhn/mcp-sentinel-core";
+/**
+ * Build the Markdown notification delivered to the originating session when a
+ * sentinel resolves.
+ *
+ * @param task - The resolved task (already carries `lastResult`/`error`).
+ * @param event - The resolution event: `completed`, `failed`, or `timeout`.
+ */
+export declare function buildNotificationText(task: SentinelTask, event: SentinelEvent): string;
+//# sourceMappingURL=notify.d.ts.map

package/dist/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../src/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE7E;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAwCtF"}

package/dist/notify.js

@@ -0,0 +1,57 @@
+/**
+ * OpenCode 2 (V2) harness — completion notification text.
+ *
+ * The message format is host-specific and therefore lives in the adapter, not
+ * in the core. It is delivered through the V2 session inbox as a synthetic
+ * message (see `src/index.ts`), not as a user prompt.
+ *
+ * @module
+ */
+/**
+ * Build the Markdown notification delivered to the originating session when a
+ * sentinel resolves.
+ *
+ * @param task - The resolved task (already carries `lastResult`/`error`).
+ * @param event - The resolution event: `completed`, `failed`, or `timeout`.
+ */
+export function buildNotificationText(task, event) {
+    switch (event) {
+        case "completed":
+            return [
+                "## Sentinel Complete",
+                "",
+                `**ID:** \`${task.id}\``,
+                `**Server:** ${task.request.server}`,
+                `**Tool:** ${task.request.tool}`,
+                `**Poll count:** ${task.pollCount}`,
+                `**Duration:** ${task.resolvedAt != null ? ((task.resolvedAt - task.createdAt) / 1000).toFixed(1) : "—"}s`,
+                "**Result:**",
+                "```json",
+                JSON.stringify(task.lastResult, null, 2),
+                "```",
+            ].join("\n");
+        case "failed":
+            return [
+                "## Sentinel Failed",
+                "",
+                `**ID:** \`${task.id}\``,
+                `**Server:** ${task.request.server}`,
+                `**Tool:** ${task.request.tool}`,
+                `**Poll count:** ${task.pollCount}`,
+                `**Error:** ${task.error}`,
+            ].join("\n");
+        case "timeout":
+            return [
+                "## Sentinel Timeout",
+                "",
+                `**ID:** \`${task.id}\``,
+                `**Server:** ${task.request.server}`,
+                `**Tool:** ${task.request.tool}`,
+                `**Poll count:** ${task.pollCount}`,
+                "**Last result:**",
+                "```json",
+                JSON.stringify(task.lastResult, null, 2),
+                "```",
+            ].join("\n");
+    }
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@gcszhn/mcp-sentinel-opencode2-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.0",
+  "description": "OpenCode 2 (V2) 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",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bunx tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\""
+  },
+  "dependencies": {
+    "@gcszhn/mcp-sentinel-core": "1.5.0",
+    "@opencode/plugin": "2.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GCS-ZHN/mcp-sentinel.git",
+    "directory": "packages/opencode2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ]
+}