@xemahq/opencode-xema-plugin 0.1.3 → 0.1.5

package/src/hooks/workspace-listing.ts

@@ -0,0 +1,175 @@
+import { readdirSync, statSync, type Dirent } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Renders the actual depth-1 contents of `/workspace` as a Markdown
+ * tree, grouped by AWP top-level slot. Appended to the system prompt
+ * by the chat-system-transform hook so the LLM sees the real layout —
+ * actual filenames, repo slugs, prior-turn deliverables — without
+ * having to spend a tool call on `glob` or `list`.
+ *
+ * Design constraints:
+ *
+ *   - **Read-only, side-effect free.** Pure fs reads. No caching state,
+ *     no writes, no network.
+ *   - **Hides platform-private slots.** `.xema/` is platform-private —
+ *     the LLM has no business reading or grep'ing it (its contents are
+ *     already in the system prompt overlay). `.opencode/` is OpenCode
+ *     runtime state (agent + skill bundles, plugin tree, snapshot
+ *     metadata) — also hidden because operating on it is never the
+ *     user's intent.
+ *   - **Bounded output.** Each directory's listing is capped at
+ *     {@link MAX_ENTRIES_PER_DIR}; overflow is summarised as
+ *     `(N more entries — use \`glob\`/\`list\` to enumerate)` so the
+ *     system prompt never balloons under sessions that accumulate
+ *     hundreds of files in `deliverables/`.
+ *   - **Stable ordering.** Entries are sorted alphabetically with
+ *     directories first, so identical filesystem state produces
+ *     identical bytes and the trailing prompt-cache window stays warm
+ *     turn-to-turn when nothing changed.
+ *   - **Cache positioning.** This block goes at the very END of the
+ *     system prompt because it is the most volatile part. Anthropic +
+ *     OpenAI prefix-cache the system prompt; everything ABOVE this
+ *     block stays cached, only this trailing block recomputes.
+ */
+export const MAX_ENTRIES_PER_DIR = 50;
+
+/**
+ * Top-level entries hidden from the listing. Keep tight: anything not
+ * in this set is rendered. The check matches on the immediate child
+ * name under `/workspace/`.
+ */
+const HIDDEN_TOP_LEVEL: ReadonlySet<string> = new Set(['.xema', '.opencode']);
+
+/**
+ * Top-level directories whose child entries are intentionally not expanded.
+ *
+ * These locations are usually implicit/noisy (dependency caches, VCS internals,
+ * virtual environments) and rarely useful in the prompt body. We still show the
+ * top-level path so the model can request targeted tooling if needed.
+ */
+const SKIP_CHILD_EXPANSION_TOP_LEVEL: ReadonlySet<string> = new Set([
+  '.git',
+  'node_modules',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.tox',
+  '.nox',
+  '.eggs',
+]);
+
+interface ListedEntry {
+  readonly name: string;
+  readonly isDirectory: boolean;
+}
+
+export function renderWorkspaceListing(workspaceRoot: string): string {
+  const lines: string[] = [
+    '## Current workspace contents (depth 1)',
+    '',
+    'This is a snapshot of `/workspace/` taken at the start of this turn. Use it to orient before reaching for `glob`, `list`, or `read`. Hidden: platform-private slots (`.xema/`, `.opencode/`).',
+    '',
+  ];
+
+  let topLevel: ListedEntry[];
+  try {
+    topLevel = readDirSorted(workspaceRoot);
+  } catch (err) {
+    // The hook is best-effort orientation. If the workspace can't be
+    // listed (extremely unusual — the workspace must exist for the
+    // session to have started), surface it inline rather than failing
+    // the whole chat call. The static overlay above this block already
+    // tells the LLM the canonical layout.
+    lines.push(`_Listing unavailable: ${(err as Error).message}_`);
+    return lines.join('\n');
+  }
+
+  const visible = topLevel.filter((entry) => !HIDDEN_TOP_LEVEL.has(entry.name));
+  if (visible.length === 0) {
+    lines.push('_(workspace is empty)_');
+    return lines.join('\n');
+  }
+
+  for (const entry of visible) {
+    lines.push(...renderTopLevelEntry(workspaceRoot, entry));
+  }
+
+  return lines.join('\n');
+}
+
+function renderTopLevelEntry(workspaceRoot: string, entry: ListedEntry): string[] {
+  const relPath = entry.name;
+  const absPath = join(workspaceRoot, entry.name);
+  if (!entry.isDirectory) {
+    return [`- \`/workspace/${relPath}\``];
+  }
+  if (SKIP_CHILD_EXPANSION_TOP_LEVEL.has(entry.name)) {
+    return [
+      `- \`/workspace/${relPath}/\` _(children omitted: known implicit/noisy directory — use \`glob\`/\`list\` if needed)_`,
+    ];
+  }
+
+  let children: ListedEntry[];
+  try {
+    children = readDirSorted(absPath);
+  } catch (err) {
+    return [`- \`/workspace/${relPath}/\` _(unreadable: ${(err as Error).message})_`];
+  }
+  if (children.length === 0) {
+    return [`- \`/workspace/${relPath}/\` _(empty)_`];
+  }
+
+  const shown = children.slice(0, MAX_ENTRIES_PER_DIR);
+  const childLines = shown.map((child) => {
+    const suffix = child.isDirectory ? '/' : '';
+    return `  - \`${child.name}${suffix}\``;
+  });
+  const overflow = children.length - shown.length;
+  const overflowLine =
+    overflow > 0
+      ? [`  - _(${overflow} more entr${overflow === 1 ? 'y' : 'ies'} — use \`glob\`/\`list\` to enumerate)_`]
+      : [];
+
+  return [`- \`/workspace/${relPath}/\``, ...childLines, ...overflowLine];
+}
+
+/**
+ * `readdirSync` with deterministic ordering: directories first, then
+ * files, each group sorted by name (case-sensitive — workspace paths
+ * are case-sensitive on the worker filesystem). Symlinks resolve to
+ * their target's type via `statSync` so a symlinked dir lists like a
+ * dir, not a file.
+ */
+function readDirSorted(dir: string): ListedEntry[] {
+  const dirents: Dirent[] = readdirSync(dir, { withFileTypes: true });
+  const entries: ListedEntry[] = dirents.map((d) => ({
+    name: d.name,
+    isDirectory: resolveIsDirectory(dir, d),
+  }));
+  entries.sort((a, b) => {
+    if (a.isDirectory !== b.isDirectory) {
+      return a.isDirectory ? -1 : 1;
+    }
+    if (a.name < b.name) {return -1;}
+    if (a.name > b.name) {return 1;}
+    return 0;
+  });
+  return entries;
+}
+
+function resolveIsDirectory(parent: string, dirent: Dirent): boolean {
+  if (dirent.isSymbolicLink()) {
+    try {
+      return statSync(join(parent, dirent.name)).isDirectory();
+    } catch {
+      // Broken symlink: classify as file so we surface its presence
+      // without crashing the listing.
+      return false;
+    }
+  }
+  return dirent.isDirectory();
+}

package/src/index.ts

@@ -0,0 +1,163 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── @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

@@ -0,0 +1,40 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── 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

@@ -0,0 +1,107 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── 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

@@ -0,0 +1,22 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── 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

@@ -0,0 +1,92 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── 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

@@ -0,0 +1,7 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── 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

@@ -0,0 +1,68 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── 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()}`;
+}