@xemahq/opencode-xema-plugin

Opencode plugin exposing Xema runtime tools and overlay hook

Overview

An Opencode plugin that registers Xema-namespaced runtime tools, a dynamic system-prompt overlay hook, and the sub-agent fan-out ceiling. The plugin is evaluated once at agent startup; it registers its tools unconditionally and defers per-role authorization to tool-execution time, where each tool reads the invocation context from the worker filesystem and rejects calls the invoking role is not permitted to make.

When to use it

• Use it to add the Xema runtime tools and prompt overlay to an Opencode agent runtime.
• Use it to bound how many sub-agents one worker may run at once.

The sub-agent fan-out ceiling

Opencode bounds how DEEP delegation may nest (subagent_depth). Nothing bounds how WIDE a turn may go, so at the platform's declared depth an unbounded branching factor is an unbounded process — every task call is forked with no pool, no semaphore and no queue.

This plugin adds the missing pool cap. It is BACKPRESSURE, not a refusal: when the worker is already running its ceiling of sub-agents, the next task call WAITS for a slot instead of being denied. An agent that cannot spawn a helper would produce a wrong answer; one that waits produces a slower right one.

Configuration exists to TIGHTEN, never to enable:

| | | |---|---| | Default | 8 concurrent task calls per worker | | Tighten with | XEMA_SUBAGENT_FANOUT_LIMIT (1..8) | | Unset or empty | the platform default — never zero, never "off" | | Above the default | refused at boot, with the reason |

Every degradation is logged: a task that waits says so and for how long, and both leak backstops (a session.idle sweep and a per-permit TTL) name what they reclaimed. A ceiling that silently stops binding is indistinguishable from working software until somebody asks.

Installation

pnpm add @xemahq/opencode-xema-plugin

Usage

import XemaPlugin from '@xemahq/opencode-xema-plugin';

// Register the plugin with your Opencode runtime configuration.
export const plugins = [XemaPlugin];

Peer requirements

• @opencode-ai/plugin >=1.0.0
• zod >=4

License

Apache-2.0 © Xema — xema.dev