@xemahq/opencode-xema-plugin 0.1.5 → 0.1.6

package/src/index.ts

@@ -1,163 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── @xemahq/opencode-xema-plugin ──
-//
-// Opencode plugin providing Xema-namespaced runtime tools (xema_memory_*)
-// and the dynamic system-prompt overlay hook.
-//
-// Lifecycle:
-//   OpenCode evaluates this plugin once at `opencode serve` startup. At that
-//   point `/workspace/context.json` does NOT yet exist — it is written per
-//   invocation by the orchestrator's XemaRuntimeMounter before the agent
-//   starts. The plugin therefore registers all tools unconditionally and
-//   defers role validation to tool-execution time, where each tool reads
-//   `context.json` from the worker filesystem.
-//
-//   Each tool's `execute()` loads session state at call time via
-//   `loadSessionStateForTool`, which reads the role's `allowedXemaTools`
-//   list straight from `context.json`'s `authority.allowedXemaTools`
-//   field (populated by llm-registry-api from the
-//   `RoleCapabilityProfile` YAMLs at
-//   `biomes/kernel/runtime/role-capabilities/`). Throws a typed error
-//   (surfaced to the LLM as a tool error) when the invoking role is not
-//   allowed.
-//
-//   Path-policy enforcement (where the agent may write, what the agent
-//   may read) is intentionally NOT done here. It lives in the rails
-//   that genuinely enforce it: workspace-proxy's symlink-aware boundary
-//   check, the harvester's manifest-driven read (off-manifest writes
-//   are orphan bytes), deliverable-specs content validation, the
-//   per-allocation gateway JWT, and pod isolation. A process-local
-//   tool.execute.before hook is trivially bypassable via `bash` and
-//   would be theatre over those rails.
-//
-// See also:
-//   - workspace protocol: runtime AGENTS.md written by the orchestrator
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { buildSessionIdleAutocommit } from './hooks/session-idle-autocommit.js';
-import { buildSystemPromptOverlay } from './hooks/system-prompt-overlay.js';
-import { info, isDebug } from './logger.js';
-import type { Hooks, Plugin, ToolDefinition } from './opencode-types.js';
-
-import {
-  buildXemaMemoryGetTool,
-  buildXemaMemorySetTool,
-} from './tools/xema-memory.js';
-
-/**
- * Defensive idempotency cache — keyed by workspace directory.
- *
- * The plugin's header contract says OpenCode calls this factory once at
- * `opencode serve` startup. Out of an abundance of caution (and because
- * `buildSystemPromptOverlay` builds closures that read disk on each
- * invocation), we cache the resolved `Hooks` per directory. Concurrent
- * factory calls return the SAME in-flight promise instead of racing.
- *
- * This guard is precautionary — there is no confirmed observed
- * double-boot in source today. Cost is two map operations; value is
- * that any future OpenCode change that calls the factory twice won't
- * double-register tools or run boot-time side effects twice.
- */
-const bootCache = new Map<string, Promise<Hooks>>();
-
-export const XemaPlugin: Plugin = async (ctx) => {
-  const { directory } = ctx;
-  const cached = bootCache.get(directory);
-  if (cached !== undefined) {
-    return cached;
-  }
-  const booting = doBoot(directory);
-  bootCache.set(directory, booting);
-  try {
-    return await booting;
-  } catch (err) {
-    // Clear on failure so the next attempt can retry instead of
-    // re-returning the rejected promise forever.
-    bootCache.delete(directory);
-    throw err;
-  }
-};
-
-async function doBoot(directory: string): Promise<Hooks> {
-  const tools = buildAllTools(directory);
-  const toolNames = Object.keys(tools).sort((a, b) => a.localeCompare(b));
-  const contextPath = join(directory, 'context.json');
-  const contextPresentAtBoot = existsSync(contextPath);
-
-  info(
-    `boot: directory=${directory} tools=${toolNames.length} [${toolNames.join(', ')}] ` +
-      `context.json=${contextPresentAtBoot ? 'present' : 'absent'} ` +
-      `debug=${isDebug() ? 'on' : 'off'}`,
-  );
-
-  const hooks: Hooks = {
-    tool: tools,
-    'experimental.chat.system.transform': buildSystemPromptOverlay(directory),
-    // Per-turn auto-commit. Listens for `session.idle` via the
-    // generic `event` channel — opencode 1.15.x does not expose a
-    // dedicated `session.idle` hook, only the event union. The handler
-    // is a no-op for sessions whose context.json does not opt in
-    // (`git.autoCommit !== 'enabled'`).
-    event: buildSessionIdleAutocommit(directory),
-  };
-  return hooks;
-}
-
-/**
- * Test-only: clear the boot cache so unit tests can observe boot()
- * being called fresh. Not exported from the package barrel.
- */
-export function __resetBootCacheForTests(): void {
-  bootCache.clear();
-}
-
-function buildAllTools(workspaceDir: string): Record<string, ToolDefinition> {
-  return {
-    xema_memory_set: buildXemaMemorySetTool(workspaceDir),
-    xema_memory_get: buildXemaMemoryGetTool(workspaceDir),
-    // Document Buddy has no propose tool: both kinds (MARKDOWN_DOCUMENT
-    // and RICH_DOCUMENT) edit a real working file at
-    // `/workspace/document/<slug>.<ext>` and the platform derives the
-    // reviewable diff (see the design notes).
-    // emit_review / emit_review_brief: deleted. Reviewers now write
-    // `deliverables/review.json` via the standard `write` tool — the
-    // deliverable-specs framework Zod-validates at harvest using the
-    // `reviewer-output` kernel-tier deliverable spec at
-    // `biomes/kernel/runtime/deliverable-specs/specs/schema/reviewer-output/`
-    // — the single source of truth for the reviewer-agent output shape
-    // consumed by `xema/review@v3`.
-    //
-    // output_surface_rescan + output_surface_status: owned by the kernel
-    // output-surface-control plugin (biomes/kernel/output-surface-control/
-    // opencode-tools/output-surface-control.ts) and registered as standalone
-    // custom tools auto-discovered by OpenCode from .opencode/tools/. The xema plugin no longer owns them.
-  };
-}
-
-export default XemaPlugin;
-
-// Named exports for consumers that want programmatic access (tests, etc.)
-export { readInvocationContext } from './context.js';
-export type { InvocationContext, InvocationRole } from './context.js';
-export * from './errors.js';
-export {
-  loadSessionState,
-  loadSessionStateForTool,
-  ensureRoleAllowed,
-  ContextMissingError,
-  RoleNotAllowedError,
-  type SessionState,
-} from './session-state.js';
-// Role-tool allowlist now lives in the per-invocation context.json
-// (`authority.allowedXemaTools`), populated by llm-registry-api from the
-// `RoleCapabilityProfile` YAMLs at biomes/kernel/runtime/role-capabilities/.
-// No re-export from workflow-contracts: the registry constant is gone.
-
-// Gate-review contract lives in `@xemahq/kernel-contracts/workflow`
-// (`ReviewSchema`, `ReviewObjectSchema`, `Review`, enum value types).
-// Consumers should import from there directly — the plugin bundles it
-// into its own `plugin.mjs` at build time but does not re-publish the
-// shape on its own surface.

package/src/logger.ts

@@ -1,40 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── opencode-xema-plugin logger ──
-//
-// Prefixed stderr/stdout logger. `info` / `warn` / `error` are always
-// emitted so operators have baseline visibility of plugin boot and
-// context-read failures without needing a flag.
-// `debug` is env-gated to avoid flooding long sessions; set
-// `XEMA_PLUGIN_DEBUG=1` on the worker (already a first-class env var on
-// the opencode-pool container envelope) to see per-hook / per-tool traces.
-//
-// All messages carry the `[opencode-xema-plugin]` prefix so they survive
-// `docker logs` grep-filtering alongside opencode's own stderr and the
-// workspace-proxy's access log.
-// ═══════════════════════════════════════════════════════════════════════════
-
-const PREFIX = '[opencode-xema-plugin]';
-
-const DEBUG_ENABLED =
-  process.env.XEMA_PLUGIN_DEBUG === '1' ||
-  process.env.XEMA_PLUGIN_DEBUG === 'true';
-
-export function info(msg: string): void {
-  // eslint-disable-next-line no-console
-  console.log(`${PREFIX} ${msg}`);
-}
-
-export function warn(msg: string): void {
-  // eslint-disable-next-line no-console
-  console.warn(`${PREFIX} ${msg}`);
-}
-
-export function debug(msg: string): void {
-  if (!DEBUG_ENABLED) return;
-  // eslint-disable-next-line no-console
-  console.log(`${PREFIX} [debug] ${msg}`);
-}
-
-export function isDebug(): boolean {
-  return DEBUG_ENABLED;
-}

package/src/opencode-types.ts

@@ -1,107 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Minimal opencode plugin type shim ──
-//
-// We re-declare only the types we consume at the plugin boundary so this
-// package does not require the full @opencode-ai/plugin package at install
-// time. The runtime contract (exported default function returning Hooks)
-// matches opencode's loader — see /tmp/opencode/packages/plugin/src/index.ts.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import type { z } from 'zod';
-
-interface ToolContext {
-  sessionID: string;
-  messageID: string;
-  agent: string;
-  directory: string;
-  worktree: string;
-  abort: AbortSignal;
-  metadata(input: { title?: string; metadata?: Record<string, unknown> }): void;
-}
-
-export interface ToolDefinition<Args extends z.ZodRawShape = z.ZodRawShape> {
-  description: string;
-  args: Args;
-  execute(
-    args: z.infer<z.ZodObject<Args>>,
-    context: ToolContext,
-  ): Promise<string>;
-}
-
-/**
- * Subset of opencode's `Model` shape passed to `experimental.chat.system.transform`.
- * The hook fires before each chat call so we can append a Xema platform
- * overlay to the system array; the model is provided to support per-
- * provider tuning later.
- */
-export interface ExperimentalChatModel {
-  providerID?: string;
-  modelID?: string;
-}
-
-export interface ExperimentalChatSystemTransformInput {
-  sessionID?: string;
-  model: ExperimentalChatModel;
-}
-
-export interface ExperimentalChatSystemTransformOutput {
-  system: string[];
-}
-
-/**
- * Generic OpenCode event delivered to the `event` hook. The upstream
- * `Event` type is a discriminated union; we type only the variants we
- * consume (currently just `session.idle`) and accept the rest as
- * `{ type: string; properties?: Record<string, unknown> }` so the
- * plugin survives new event types added by opencode without a typings
- * bump.
- */
-export type OpencodeSessionIdleEvent = {
-  type: 'session.idle';
-  properties: { sessionID: string };
-};
-
-export type OpencodeEvent =
-  | OpencodeSessionIdleEvent
-  | { type: string; properties?: Record<string, unknown> };
-
-export interface Hooks {
-  tool?: Record<string, ToolDefinition>;
-  /**
-   * Fires once per chat call. We append the rendered Xema system overlay
-   * to `output.system` so the LLM sees the AWP base layer + deliverable
-   * contract + authority + retry context as authoritative platform
-   * context — separate from the project-level `/workspace/AGENTS.md`.
-   */
-  'experimental.chat.system.transform'?: (
-    input: ExperimentalChatSystemTransformInput,
-    output: ExperimentalChatSystemTransformOutput,
-  ) => Promise<void> | void;
-  /**
-   * Generic opencode event hook. OpenCode 1.15.x exposes session
-   * lifecycle as discriminated events on this channel rather than as
-   * dedicated hooks. The xema plugin uses it to react to
-   * `session.idle` (per-turn auto-commit). All other event types are
-   * ignored.
-   */
-  event?: (input: { event: OpencodeEvent }) => Promise<void> | void;
-}
-
-interface PluginInput {
-  directory: string;
-  worktree: string;
-  serverUrl: URL;
-}
-
-export type Plugin = (input: PluginInput) => Promise<Hooks>;
-
-/**
- * The opencode `tool()` helper is a pass-through identity function. We
- * re-declare it here so plugin authors can use `tool({...})` exactly as
- * they would via @opencode-ai/plugin.
- */
-export function tool<Args extends z.ZodRawShape>(
-  input: ToolDefinition<Args>,
-): ToolDefinition<Args> {
-  return input;
-}

package/src/plugin-entry.ts

@@ -1,22 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── OpenCode plugin entry point ──
-//
-// OpenCode v1.4.x's plugin loader inspects the ESM module's exports and
-// expects to find a single plugin factory. When the module re-exports
-// additional identifiers (error classes, constants, helper utilities), the
-// loader's heuristic picks the wrong export and fails with
-// "Plugin export is not a function". The tools then silently fail to
-// register — the agent boots, the model is still resolvable, but every
-// prompt that references a `xema_*` tool dies at tool-dispatch time
-// with "Model tried to call unavailable tool".
-//
-// This file is the bundle entry for the worker-image build. It re-exports
-// ONLY the plugin factory (as the default export AND as a named export for
-// loaders that look for either). Everything else — errors, runtime helpers,
-// the role-capability registry — stays available to TypeScript consumers via
-// the package's regular `index.ts` barrel, which is the consumer-facing
-// entry (not the runtime plugin entry). The two entry points let the
-// programmatic API stay rich without breaking OpenCode's plugin contract.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export { XemaPlugin as default, XemaPlugin } from './index.js';

package/src/session-state.ts

@@ -1,92 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Session state + role allowlist ──
-//
-// The xema plugin is evaluated once at `opencode serve` startup. That is
-// BEFORE the orchestrator writes /workspace/context.json (which is done per
-// invocation by XemaRuntimeMounter). Every tool and hook therefore reads
-// context.json lazily at call time through this module.
-//
-// Role-tool allowlist: source of truth is the `RoleCapabilityProfile`
-// YAMLs at `biomes/kernel/runtime/role-capabilities/`, resolved by
-// llm-registry-api's `agent-run-context.service.ts` and written into the
-// `authority.allowedXemaTools` field of context.json. The plugin reads
-// the list straight off context — adding/changing a role's tool list
-// happens in the YAML, never here.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import {
-  readInvocationContext,
-  type InvocationContext,
-  type InvocationRole,
-} from './context.js';
-
-export interface SessionState {
-  ctx: InvocationContext;
-}
-
-export class ContextMissingError extends Error {
-  readonly code = 'XEMA_CONTEXT_MISSING';
-  constructor(public readonly workspaceDir: string) {
-    super(
-      `/workspace/context.json not found in ${workspaceDir}. The xema plugin ` +
-        `cannot operate without invocation context — the orchestrator must ` +
-        `write context.json before the agent starts.`,
-    );
-  }
-}
-
-export class RoleNotAllowedError extends Error {
-  readonly code = 'XEMA_ROLE_NOT_ALLOWED';
-  constructor(
-    public readonly role: InvocationRole,
-    public readonly toolName: string,
-    public readonly allowedTools: string[],
-  ) {
-    super(
-      `Role "${role}" is not allowed to call "${toolName}". Allowed tools ` +
-        `for this role: [${allowedTools.join(', ')}].`,
-    );
-  }
-}
-
-/**
- * Read /workspace/context.json from the worker filesystem. Throws
- * ContextMissingError if context.json is not present — callers inside a
- * tool.execute should let this propagate (opencode turns it into a tool
- * error). Hook callers should treat a missing context as a non-xema
- * session instead.
- */
-export function loadSessionState(workspaceDir: string): SessionState {
-  const ctx = readInvocationContext(workspaceDir);
-  if (!ctx) {
-    throw new ContextMissingError(workspaceDir);
-  }
-  return { ctx };
-}
-
-export function ensureRoleAllowed(
-  ctx: InvocationContext,
-  toolName: string,
-): void {
-  const allowed = ctx.authority.allowedXemaTools;
-  if (!allowed.includes(toolName)) {
-    throw new RoleNotAllowedError(
-      ctx.invocation.role,
-      toolName,
-      [...allowed].sort((a, b) => a.localeCompare(b)),
-    );
-  }
-}
-
-/**
- * Load session state and assert the invoking role may call the given tool.
- * Used by every Xema-namespaced tool at the top of its execute().
- */
-export function loadSessionStateForTool(
-  workspaceDir: string,
-  toolName: string,
-): SessionState {
-  const state = loadSessionState(workspaceDir);
-  ensureRoleAllowed(state.ctx, toolName);
-  return state;
-}

package/src/tools/runtime.ts

@@ -1,7 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Tool runtime helpers ──
-// Re-export from the root session-state module. Kept as a thin barrel so
-// each Xema-namespaced tool has a stable import path.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export { loadSessionStateForTool } from '../session-state.js';

package/src/tools/service-token.ts

@@ -1,68 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Worker service-token reader ──
-//
-// The opencode worker authenticates against platform services with a
-// per-allocation Keycloak service JWT. The JWT carries the `xema_org_id`
-// org-scope claim that `ServiceTokenGuard` cross-checks against
-// the tenant header (`X-Xema-Org-Id`, legacy `X-Org-Id`) on every
-// downstream call — replay against a different tenant is rejected
-// fail-fast at the receiving service.
-// workspace-proxy — running in the same pod — writes that JWT to a file
-// and refreshes it mid-session via `PUT /control/service-token`.
-//
-// The `xema_*` tools read this file FRESH on every call (never cache it):
-// a cached value would go stale the moment workspace-proxy swaps in a
-// refreshed token, silently producing 401s for the rest of the session.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { readFileSync } from 'node:fs';
-
-/**
- * Path the worker service token is written to. Configurable via
- * `XEMA_SERVICE_TOKEN_PATH`; defaults to `/run/xema/service-token`. Must
- * stay aligned with `serviceTokenPath()` in `biomes/workspace-proxy/api/workspace-proxy`.
- */
-function serviceTokenPath(): string {
-  return process.env['XEMA_SERVICE_TOKEN_PATH']?.trim() || '/run/xema/service-token';
-}
-
-/**
- * Read the worker service JWT from disk, fresh. Throws a clear fail-fast
- * error when the file is missing or empty — the worker cannot reach
- * platform services without it, and silently sending no `Authorization`
- * header would just surface as opaque 401s deeper in the stack.
- */
-export function readServiceToken(): string {
-  const path = serviceTokenPath();
-  let raw: string;
-  try {
-    raw = readFileSync(path, 'utf8');
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === 'ENOENT') {
-      throw new Error(
-        `Worker service token file is missing at ${path}. workspace-proxy ` +
-          'must write the per-allocation Keycloak JWT (via the session ' +
-          'bundle or PUT /control/service-token) before xema_* tools run.',
-      );
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to read worker service token at ${path}: ${message}`);
-  }
-  const token = raw.trim();
-  if (!token) {
-    throw new Error(
-      `Worker service token file at ${path} is empty. workspace-proxy ` +
-        'must write a non-empty per-allocation Keycloak JWT.',
-    );
-  }
-  return token;
-}
-
-/**
- * Convenience wrapper returning the `Authorization: Bearer <jwt>` header
- * value for the worker service token.
- */
-export function serviceTokenAuthorizationHeader(): string {
-  return `Bearer ${readServiceToken()}`;
-}

package/src/tools/shared.ts

@@ -1,16 +0,0 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-
-export function writeOutputFile(
-  workspaceDir: string,
-  relativePath: string,
-  content: string,
-): void {
-  const fullPath = join(workspaceDir, relativePath);
-  mkdirSync(dirname(fullPath), { recursive: true });
-  writeFileSync(fullPath, content, 'utf-8');
-}
-
-export function toJsonString(value: unknown): string {
-  return JSON.stringify(value, null, 2);
-}