@xemahq/worker-runtime-opencode 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/worker-runtime-opencode",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Opencode WorkerRuntime driver — wraps the workspace-proxy control-session handshake and the opencode SSE event stream behind the kernel WorkerRuntime contract.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -18,8 +18,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "devDependencies": {
     "@types/jest": "^30.0.0",

package/src/index.ts

@@ -1,28 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── @xemahq/worker-runtime-opencode — barrel export ──
-//
-// opencode driver behind the
-// `@xemahq/kernel-contracts/worker-runtime` interface. The orchestrator and
-// session-launch services depend on THIS package's `WorkerRuntime` API;
-// they never reach into `biomes/workspace-proxy/api/workspace-proxy/` or `apps/opencode-pool-api/`.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export {
-  OpencodeWorkerRuntime,
-  OPENCODE_CONNECTOR_KIND,
-  type OpencodePodSpec,
-} from './lib/opencode-worker-runtime';
-export { createOpencodeWorkerRuntime } from './lib/factory';
-export {
-  buildOpencodeSessionBundle,
-  computeSessionBindingRevision,
-  computeStaticBundleFingerprint,
-  decodeOpencodeSessionBundle,
-  type OpencodeBundleSubAgent,
-  type OpencodeSessionBundlePayload,
-} from './lib/session-bundle';
-export type {
-  BundleCallerContext,
-  OpencodeRuntimeConfig,
-  WorkerRef,
-} from './lib/worker-ref';

package/src/lib/factory.ts

@@ -1,56 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── OpencodeWorkerRuntime — factory ──
-//
-// Single entry-point the orchestrator calls per allocated worker. Keeping
-// construction behind a factory makes future test-injection seams (mock
-// fetch, mock SSE body) trivial without exposing the class constructor's
-// shape to consumers.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { OpencodeWorkerRuntime } from './opencode-worker-runtime';
-import type { OpencodeRuntimeConfig } from './worker-ref';
-
-/**
- * Construct an `OpencodeWorkerRuntime` bound to a specific worker.
- *
- * The orchestrator calls this once `workload-runtime-api` returns a
- * scheduled worker + the per-allocation service token has been minted.
- */
-export function createOpencodeWorkerRuntime(
-  config: OpencodeRuntimeConfig,
-): OpencodeWorkerRuntime {
-  validate(config);
-  return new OpencodeWorkerRuntime(config);
-}
-
-function validate(config: OpencodeRuntimeConfig): void {
-  const ref = config.workerRef;
-  if (!ref.workerId.trim()) {
-    throw new Error('OpencodeRuntimeConfig.workerRef.workerId is required.');
-  }
-  if (!ref.controlPlaneUrl.trim()) {
-    throw new Error('OpencodeRuntimeConfig.workerRef.controlPlaneUrl is required.');
-  }
-  if (!ref.region.trim()) {
-    throw new Error('OpencodeRuntimeConfig.workerRef.region is required.');
-  }
-  if (!ref.allocationId.trim()) {
-    throw new Error('OpencodeRuntimeConfig.workerRef.allocationId is required.');
-  }
-  if (!ref.workerServiceToken.trim()) {
-    throw new Error('OpencodeRuntimeConfig.workerRef.workerServiceToken is required.');
-  }
-  if (!ref.workerControlPassword.trim()) {
-    throw new Error('OpencodeRuntimeConfig.workerRef.workerControlPassword is required.');
-  }
-  const caller = config.caller;
-  if (!caller.orgId.trim()) {
-    throw new Error('OpencodeRuntimeConfig.caller.orgId is required.');
-  }
-  if (!caller.projectId.trim()) {
-    throw new Error('OpencodeRuntimeConfig.caller.projectId is required.');
-  }
-  if (!caller.authToken.trim()) {
-    throw new Error('OpencodeRuntimeConfig.caller.authToken is required.');
-  }
-}

package/src/lib/opencode-worker-runtime.ts

@@ -1,344 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── OpencodeWorkerRuntime — v1 WorkerRuntime impl ──
-//
-// A thin adapter that wraps the existing workspace-proxy control plane +
-// opencode SSE stream behind the kernel `WorkerRuntime` interface.
-//
-// This impl deliberately does NOT import from `biomes/workspace-proxy/api/workspace-proxy/` or
-// `apps/opencode-pool-api/` — the wire format is the contract. The same
-// HTTP endpoints exposed by workspace-proxy are called by this driver
-// from outside the pod (the orchestrator runs separately).
-// ═══════════════════════════════════════════════════════════════════════════
-
-import {
-  HookKind,
-  WorkerRuntimeKind,
-  type BuildBundleInput,
-  type BuildPodSpecInput,
-  type SessionBundle,
-  type WorkerRuntime,
-  type WorkerRuntimeCapabilityBits,
-} from '@xemahq/kernel-contracts/worker-runtime';
-import type { AbstractMount } from '@xemahq/kernel-contracts/workspace-storage';
-
-import {
-  buildOpencodeSessionBundle,
-  decodeOpencodeSessionBundle,
-  type OpencodeSessionBundlePayload,
-} from './session-bundle';
-import type { OpencodeRuntimeConfig, WorkerRef } from './worker-ref';
-
-/**
- * Wire connector kind a session must have bound in scope before the
- * orchestrator may select this runtime. Surfaced as a string at the
- * kernel boundary (see `WorkerRuntime.connectorKindRequired` —
- * `packages/kernel/worker-runtime-contracts/src/lib/runtime.ts:84`).
- *
- * `'opencode-default'` is the LLM-gateway-backed connector that ships
- * by default in every org, and the only one today. A future connector bound to
- * a different runtime would expose its own kind here and select that runtime.
- */
-export const OPENCODE_CONNECTOR_KIND = 'opencode-default';
-
-/**
- * Upper bound for a single `PUT /control/session-bundle` apply (F2). Chosen
- * comfortably above a legitimate cold apply — workspace-proxy materializes
- * (~sub-second) then restarts opencode with a 30s health-wait ceiling, so a
- * correct apply completes in well under a minute even on a loaded node — and
- * far below the ~256s OS TCP read timeout that a stuck/black-holed handler
- * would otherwise cost. Keeps a wedged apply from stalling the whole allocation
- * for minutes.
- */
-const APPLY_SESSION_BUNDLE_TIMEOUT_MS = 120_000;
-
-const OPENCODE_CAPABILITIES: WorkerRuntimeCapabilityBits = {
-  hotMcp: true,
-  hotModelSwap: true,
-  sessionFork: true,
-  subAgentCrud: true,
-  hooks: [
-    HookKind.ToolExecuteBefore,
-    HookKind.ToolExecuteAfter,
-    HookKind.SessionIdle,
-    HookKind.SessionStart,
-  ],
-  previewSupervisor: true,
-  gatewayAttributedCalls: true,
-  llmEndpointOverride: true,
-};
-
-/**
- * Shape the K8s scheduler in `biomes/workload-runtime/api/workload-runtime-api/src/scheduler/k8s/`
- * narrows when `buildPodSpec` returns. The orchestrator stays
- * runtime-agnostic; the scheduler is the only consumer that interprets
- * these fields. Mirrors `WorkloadContainerSpecDto` keys.
- */
-export interface OpencodePodSpec {
-  readonly runtimeKind: WorkerRuntimeKind;
-  readonly image: string;
-  readonly env: Readonly<Record<string, string>>;
-  readonly mounts: readonly AbstractMount[];
-  readonly region?: string;
-  /**
-   * Translated scheduler-side hint. For k8s this becomes
-   * `nodeAffinity` on `topology.kubernetes.io/region`; for Docker it
-   * becomes a container label. The scheduler picks the right shape.
-   */
-  readonly nodeAffinity?: {
-    readonly key: string;
-    readonly values: readonly string[];
-  };
-  readonly requestedCapabilities: BuildPodSpecInput['capabilities'];
-}
-
-/**
- * The opencode-runtime adapter. ONE instance per (allocation, worker)
- * — the worker identity is bound at construction so the kernel methods
- * stay parameter-free per the contract.
- */
-export class OpencodeWorkerRuntime implements WorkerRuntime {
-  readonly kind = WorkerRuntimeKind.Opencode;
-  readonly capabilities = OPENCODE_CAPABILITIES;
-  readonly connectorKindRequired = OPENCODE_CONNECTOR_KIND;
-  readonly autoCommitHookSupported = true;
-
-  private workerRef: WorkerRef;
-  private caller: OpencodeRuntimeConfig['caller'];
-
-  constructor(config: OpencodeRuntimeConfig) {
-    this.workerRef = config.workerRef;
-    this.caller = config.caller;
-  }
-
-  /**
-   * Translate the schedule-agnostic input to the OpencodePodSpec shape
-   * the K8s/Docker schedulers consume. The kernel contract types the
-   * return as `unknown` so the scheduler boundary is the only place that
-   * narrows. No I/O — pure transform.
-   */
-  buildPodSpec(input: BuildPodSpecInput): Promise<OpencodePodSpec> {
-    const spec: OpencodePodSpec = {
-      runtimeKind: this.kind,
-      image: input.image,
-      env: input.env,
-      mounts: input.mounts,
-      ...(input.region !== undefined ? { region: input.region } : {}),
-      ...(input.region !== undefined
-        ? {
-            nodeAffinity: {
-              key: 'topology.kubernetes.io/region',
-              values: [input.region],
-            },
-          }
-        : {}),
-      requestedCapabilities: input.capabilities,
-    };
-    return Promise.resolve(spec);
-  }
-
-  /**
-   * Compose a SessionBundle. The fingerprint short-circuits the
-   * workspace-proxy apply call on the next `applySessionBundle`.
-   */
-  async buildSessionBundle(input: BuildBundleInput): Promise<SessionBundle> {
-    const { bundle } = buildOpencodeSessionBundle(
-      input,
-      this.workerRef.allocationId,
-      this.caller,
-      this.workerRef.bindingEpoch,
-      // Per-allocation worker service JWT minted by the orchestrator — the
-      // sole owner of this credential. Delivered on the orchestrator's
-      // initial applySessionBundle so `/run/xema/service-token` exists before
-      // working-file arming; the proxy never clears it on later re-applies.
-      this.workerRef.workerServiceToken,
-    );
-    return bundle;
-  }
-
-  /**
-   * Push a built bundle to the live worker.
-   *
-   * Endpoint: `PUT <controlPlaneUrl>/control/session-bundle`
-   * Source-of-truth at `biomes/workspace-proxy/api/workspace-proxy/src/handlers/control-plane.ts:377`.
-   *
-   * Response contract:
-   *   - 200 `{ unchanged: true, ... }`  ← fingerprint matched; no work done.
-   *   - 200 `{ unchanged: false, applied: true, ... }` ← re-materialized.
-   *   - 4xx/5xx ← failure; this method throws.
-   */
-  async applySessionBundle(bundle: SessionBundle): Promise<void> {
-    const payload = decodeOpencodeSessionBundle(bundle);
-    const url = joinUrl(
-      this.workerRef.controlPlaneUrl,
-      '/control/session-bundle',
-    );
-    // F2 — bound the apply. workspace-proxy's `/control/session-bundle` handler
-    // is internally bounded (materialize + a 30s opencode-restart health wait +
-    // token injection), so a correct apply completes in well under a minute even
-    // on a cold node. Without an explicit signal a *stuck* handler (e.g. the
-    // worker pod deleted mid-apply, or a restart storm preempting the restart)
-    // black-holes the connection until the OS TCP read timeout (~256s), so the
-    // orchestrator burns ~4 minutes per doomed attempt before it can compensate
-    // and retry. An `AbortSignal.timeout` well above a legitimate cold apply but
-    // far below the kernel ceiling converts that into a fast, deterministic
-    // failure the saga can act on immediately. This is a bounded external-call
-    // timeout (allowed by the Constitution), NOT a sleep to mask a race.
-    let response: Response;
-    try {
-      response = await fetch(url, {
-        method: 'PUT',
-        headers: this.authHeaders(),
-        body: JSON.stringify(payload),
-        signal: AbortSignal.timeout(APPLY_SESSION_BUNDLE_TIMEOUT_MS),
-      });
-    } catch (err) {
-      // `AbortSignal.timeout` aborts with a `TimeoutError` DOMException; some
-      // runtimes surface the abort as `AbortError`. The only abort source here
-      // is our own timeout, so treat either as the bounded-apply timeout.
-      if (
-        err instanceof DOMException &&
-        (err.name === 'TimeoutError' || err.name === 'AbortError')
-      ) {
-        throw new Error(
-          `applySessionBundle timed out after ${APPLY_SESSION_BUNDLE_TIMEOUT_MS}ms ` +
-            `waiting on ${url} — the worker control plane accepted the connection ` +
-            'but never responded (stuck handler / reaped pod). Failing fast so the ' +
-            'allocation saga can compensate and retry.',
-        );
-      }
-      throw err;
-    }
-    if (!response.ok) {
-      const body = await safeReadText(response);
-      throw new Error(
-        `applySessionBundle failed: HTTP ${response.status} from ${url} — ${body}`,
-      );
-    }
-    const parsed = (await response.json()) as ApplyBundleResponse;
-    assertApplyResponseOk(parsed, payload);
-  }
-
-  /**
-   * Pause the worker.
-   *
-   * Endpoint: `POST <controlPlaneUrl>/control/pause` — the wire shape is
-   * `200 { paused: true, state: { ... } }` (source at
-   * `biomes/workspace-proxy/api/workspace-proxy/src/handlers/control-pause-resume.ts`). The
-   * runtime carries the current bundle fingerprint + allocationId so
-   * workspace-proxy can stamp them on the pause marker; resume can
-   * then short-circuit if the bundle is unchanged.
-   */
-  async pause(): Promise<void> {
-    const url = joinUrl(this.workerRef.controlPlaneUrl, '/control/pause');
-    const body: ControlPauseBody = {
-      allocationId: this.workerRef.allocationId,
-    };
-    const response = await fetch(url, {
-      method: 'POST',
-      headers: this.authHeaders(),
-      body: JSON.stringify(body),
-    });
-    if (!response.ok) {
-      const text = await safeReadText(response);
-      throw new Error(
-        `OpencodeWorkerRuntime.pause failed: HTTP ${response.status} from ${url} — ${text}`,
-      );
-    }
-  }
-
-  /**
-   * Resume a previously-paused worker.
-   *
-   * Endpoint: `POST <controlPlaneUrl>/control/resume` — the wire shape is
-   * `200 { resumed: true, state: { ... } }`. A 409
-   * `PAUSE_RESUME_FINGERPRINT_MISMATCH` from workspace-proxy means the
-   * caller must re-apply the bundle (`applySessionBundle`) before
-   * retrying — surfaced as a typed error here so the orchestrator can
-   * branch.
-   */
-  async resume(): Promise<void> {
-    const url = joinUrl(this.workerRef.controlPlaneUrl, '/control/resume');
-    const response = await fetch(url, {
-      method: 'POST',
-      headers: this.authHeaders(),
-      body: JSON.stringify({}),
-    });
-    if (!response.ok) {
-      const text = await safeReadText(response);
-      throw new Error(
-        `OpencodeWorkerRuntime.resume failed: HTTP ${response.status} from ${url} — ${text}`,
-      );
-    }
-  }
-
-  private authHeaders(): Record<string, string> {
-    // workspace-proxy guards every control/session route with HTTP Basic
-    // auth (`opencode:<OPENCODE_SERVER_PASSWORD>`); a Bearer token is
-    // rejected (scheme must be `Basic`). The worker's egress JWT
-    // (workerServiceToken) is a DIFFERENT credential delivered into the pod
-    // separately — never the inbound control credential.
-    const encoded = Buffer.from(
-      `opencode:${this.workerRef.workerControlPassword}`,
-    ).toString('base64');
-    return {
-      Authorization: `Basic ${encoded}`,
-      'Content-Type': 'application/json',
-    };
-  }
-}
-
-/**
- * Body shape for `POST /control/pause`. The fingerprint slot is left
- * undefined here because the runtime adapter doesn't track the last
- * applied bundle fingerprint — the orchestrator stamps it via
- * `applySessionBundle` and workspace-proxy persists it in the marker.
- */
-interface ControlPauseBody {
-  readonly allocationId: string;
-  readonly fingerprint?: string;
-}
-
-interface ApplyBundleResponse {
-  readonly unchanged?: boolean;
-  readonly applied?: boolean;
-  readonly state?: {
-    readonly allocationId?: string | null;
-    readonly setupAt?: string | null;
-  };
-  readonly error?: string;
-  readonly status?: string;
-}
-
-function assertApplyResponseOk(
-  parsed: ApplyBundleResponse,
-  payload: OpencodeSessionBundlePayload,
-): void {
-  if (parsed.unchanged === true) return;
-  if (parsed.applied === true) {
-    const stateAllocationId = parsed.state?.allocationId ?? null;
-    if (stateAllocationId !== payload.allocationId) {
-      throw new Error(
-        `applySessionBundle returned a state allocationId (${String(stateAllocationId)}) that disagrees with the requested allocationId (${payload.allocationId}). The worker rebound to another session — fail fast.`,
-      );
-    }
-    return;
-  }
-  throw new Error(
-    `applySessionBundle: workspace-proxy returned an unexpected shape — ${JSON.stringify(parsed)}`,
-  );
-}
-
-async function safeReadText(response: Response): Promise<string> {
-  try {
-    return await response.text();
-  } catch {
-    return '<unreadable response body>';
-  }
-}
-
-function joinUrl(base: string, path: string): string {
-  const trimmedBase = base.endsWith('/') ? base.slice(0, -1) : base;
-  const prefixedPath = path.startsWith('/') ? path : `/${path}`;
-  return `${trimmedBase}${prefixedPath}`;
-}
-

package/src/lib/session-bundle.ts

@@ -1,232 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Opencode session-bundle encoding ──
-//
-// Translates the kernel-shape `BuildBundleInput` into the on-the-wire
-// payload that workspace-proxy's `PUT /control/session-bundle` handler
-// expects (defined at `biomes/workspace-proxy/api/workspace-proxy/src/handlers/control-plane.ts:816`
-// — `interface BundlePayload`).
-//
-// `staticFingerprint` is the reusable runtime-template compatibility
-// identity. `bindingRevision` / `bindingEpoch` identify the tenant/session
-// state applied after a compatible worker is claimed.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { createHash } from 'node:crypto';
-
-import type {
-  BuildBundleInput,
-  SessionBundle,
-} from '@xemahq/kernel-contracts/worker-runtime';
-
-import type { BundleCallerContext } from './worker-ref';
-
-/**
- * Sub-agent entry as the workspace-proxy bundle handler expects it.
- * Workspace-proxy validates this shape at runtime; mismatched fields
- * fail with HTTP 400. Keep field names byte-for-byte aligned with the
- * `BundlePayload.subAgents` parser.
- */
-export interface OpencodeBundleSubAgent {
-  readonly slug: string;
-  readonly alias?: string;
-  readonly stageKey?: string;
-}
-
-/**
- * Fully-formed JSON body for `PUT /control/session-bundle`. Mirrors
- * `biomes/workspace-proxy/api/workspace-proxy/src/handlers/control-plane.ts:816` (`BundlePayload`).
- */
-export interface OpencodeSessionBundlePayload {
-  readonly allocationId: string;
-  readonly caller: BundleCallerContext;
-  readonly opencodeConfigBase64: string;
-  readonly primaryAgent: { readonly slug: string };
-  readonly subAgents: readonly OpencodeBundleSubAgent[];
-  readonly modelOverride?: string;
-  readonly mcpConfig?: string;
-  /**
-   * Per-allocation worker service JWT. workspace-proxy persists it to
-   * `/run/xema/service-token`, where the in-worker `xema_*` tools + the KB
-   * working-file adapter read it to authenticate their callbacks. The
-   * orchestrator is the sole minter/owner and delivers it on its initial
-   * `applySessionBundle`; the proxy writes-when-present and NEVER clears it,
-   * so later agent-session-api re-applies (which omit it) leave the token
-   * intact. Deliberately EXCLUDED from both hashes: raw credentials must
-   * never enter compatibility or binding identities.
-   */
-  readonly serviceToken?: string;
-  readonly staticFingerprint: string;
-  readonly bindingRevision: string;
-  readonly bindingEpoch: number;
-}
-
-/**
- * Stable canonical JSON encoder. Keys are sorted alphabetically at every
- * object level; undefined values are stripped. The output is the input
- * to the SHA-256 fingerprint and MUST be deterministic.
- */
-function canonicalize(value: unknown): unknown {
-  if (value === null || typeof value !== 'object') return value;
-  if (Array.isArray(value)) return value.map((v) => canonicalize(v));
-  const obj = value as Record<string, unknown>;
-  const out: Record<string, unknown> = {};
-  for (const key of Object.keys(obj).sort()) {
-    const v = obj[key];
-    if (v === undefined) continue;
-    out[key] = canonicalize(v);
-  }
-  return out;
-}
-
-/**
- * Compute the static compatibility fingerprint. It MUST be stable across
- * structurally-identical inputs and MUST change when ANY of:
- *   - primary agent slug,
- *   - sub-agent set (slug + alias + stageKey),
- *   - opencode config bytes,
- *   - MCP config blob,
- * differs.
- *
- * Per-invocation model selection is binding state and is intentionally
- * excluded from this runtime-template identity.
- */
-export function computeStaticBundleFingerprint(
-  input: BuildBundleInput,
-): string {
-  const sortedSubAgents = [...input.subAgents].sort();
-  const canonical = canonicalize({
-    primaryAgent: input.primaryAgent,
-    subAgents: sortedSubAgents,
-    // Static key stays `opencodeConfigBase64` to match workspace-proxy's
-    // wire-side fingerprint; only the kernel input field was renamed.
-    opencodeConfigBase64: input.runtimeConfigBase64,
-    mcpConfig: input.mcpConfig,
-  });
-  const hash = createHash('sha256');
-  hash.update(JSON.stringify(canonical));
-  return hash.digest('hex');
-}
-
-/**
- * Hash only non-secret tenant/session identifiers. Actor and service tokens
- * are deliberately absent so credential rotation cannot leak into hashes.
- */
-export function computeSessionBindingRevision(
-  allocationId: string,
-  caller: BundleCallerContext,
-): string {
-  return createHash('sha256')
-    .update(
-      JSON.stringify(
-        canonicalize({
-          allocationId,
-          orgId: caller.orgId,
-          projectId: caller.projectId,
-          sessionId: caller.sessionId,
-        }),
-      ),
-    )
-    .digest('hex');
-}
-
-/**
- * Build the wire payload + opaque `SessionBundle` the kernel contract
- * exposes. The payload itself is base64-encoded so `SessionBundle` stays
- * an opaque blob at the kernel boundary (per the contract docs at
- * `packages/kernel/worker-runtime-contracts/src/lib/runtime.ts:66`).
- */
-export function buildOpencodeSessionBundle(
-  input: BuildBundleInput,
-  allocationId: string,
-  caller: BundleCallerContext,
-  bindingEpoch: number,
-  workerServiceToken: string | undefined,
-): {
-  readonly payload: OpencodeSessionBundlePayload;
-  readonly bundle: SessionBundle;
-} {
-  if (!input.primaryAgent.trim()) {
-    throw new Error('BuildBundleInput.primaryAgent must be a non-empty slug.');
-  }
-  if (!allocationId.trim()) {
-    throw new Error('allocationId must be a non-empty string.');
-  }
-  if (!Number.isSafeInteger(bindingEpoch) || bindingEpoch < 1) {
-    throw new Error('bindingEpoch must be a positive safe integer.');
-  }
-  const opencodeConfigBase64 = input.runtimeConfigBase64 ?? '';
-  if (!opencodeConfigBase64) {
-    throw new Error(
-      'BuildBundleInput.runtimeConfigBase64 is required by the opencode runtime — the workspace-proxy bundle handler treats an empty config as a 400.',
-    );
-  }
-  const staticFingerprint = computeStaticBundleFingerprint(input);
-  const bindingRevision = computeSessionBindingRevision(allocationId, caller);
-
-  const subAgents: readonly OpencodeBundleSubAgent[] = input.subAgents.map(
-    (slug) => ({ slug }),
-  );
-
-  // Build the payload, stripping undefined optionals so canonical JSON
-  // diff stays stable and the workspace-proxy parser does not error on
-  // an explicit `undefined`. The intermediate `Mutable<>` shape lets us
-  // add only the optional fields that are actually set, which keeps
-  // `exactOptionalPropertyTypes: true` happy.
-  const payload: OpencodeSessionBundlePayload = {
-    allocationId,
-    caller,
-    opencodeConfigBase64,
-    primaryAgent: { slug: input.primaryAgent },
-    subAgents,
-    staticFingerprint,
-    bindingRevision,
-    bindingEpoch,
-    ...(input.modelOverride === undefined
-      ? {}
-      : { modelOverride: input.modelOverride }),
-    ...(input.mcpConfig === undefined ? {} : { mcpConfig: input.mcpConfig }),
-    // Credential — carried on the payload but NOT in either hash, so a token
-    // refresh never churns compatibility or binding identity. Omitted when
-    // empty so the proxy's write-when-present path
-    // is a no-op rather than clobbering an existing token with "".
-    ...(workerServiceToken ? { serviceToken: workerServiceToken } : {}),
-  };
-
-  const payloadJson = JSON.stringify(payload);
-  const payloadBase64 = Buffer.from(payloadJson, 'utf8').toString('base64');
-  return {
-    payload,
-    bundle: { fingerprint: staticFingerprint, payloadBase64 },
-  };
-}
-
-/**
- * Decode a kernel `SessionBundle` back into the opencode-specific payload.
- * Used by `applySessionBundle` so the runtime stays stateless between
- * `buildSessionBundle` and `applySessionBundle` (the kernel contract
- * does not pass the input through, only the opaque bundle).
- */
-export function decodeOpencodeSessionBundle(
-  bundle: SessionBundle,
-): OpencodeSessionBundlePayload {
-  let parsed: unknown;
-  try {
-    const json = Buffer.from(bundle.payloadBase64, 'base64').toString('utf8');
-    parsed = JSON.parse(json);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      `SessionBundle.payloadBase64 is not a valid base64-encoded JSON object: ${msg}`,
-    );
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error('SessionBundle payload must decode to a JSON object.');
-  }
-  const obj = parsed as { readonly staticFingerprint?: unknown };
-  if (obj.staticFingerprint !== bundle.fingerprint) {
-    throw new Error(
-      `SessionBundle.fingerprint (${bundle.fingerprint}) disagrees with the encoded payload.staticFingerprint (${String(obj.staticFingerprint)}). Refusing to apply a tampered bundle.`,
-    );
-  }
-  return parsed as OpencodeSessionBundlePayload;
-}

package/src/lib/worker-ref.ts

@@ -1,86 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Opencode runtime — worker reference & runtime config ──
-//
-// The kernel `WorkerRuntime` contract intentionally hides the target-worker
-// identity inside the driver instance. Each opencode runtime is constructed
-// for ONE allocated worker pod; the `WorkerRef` is that identity. This
-// shape MAY graduate to `@xemahq/kernel-contracts/worker-runtime` once a second
-// runtime impl confirms the fields it actually needs.
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Identifies a single live worker pod for an opencode runtime instance.
- * Constructed by the orchestrator after `workload-runtime-api`
- * schedule + ready callbacks resolve.
- */
-export interface WorkerRef {
-  /** Stable id assigned by `workload-runtime-api` at schedule time. */
-  readonly workerId: string;
-  /**
-   * Base URL of the workspace-proxy control plane running INSIDE the pod
-   * (cluster-internal). e.g. `https://workspace-proxy.<ns>.svc.cluster.local:<port>`.
-   * The opencode runtime never talks to opencode directly — every wire call
-   * lands on workspace-proxy, which proxies into the in-pod opencode server.
-   */
-  readonly controlPlaneUrl: string;
-  /** Region the worker is scheduled in; surfaced for observability. */
-  readonly region: string;
-  /**
-   * Allocation id minted by the orchestrator. Included on every
-   * `/control/session-bundle` PUT so workspace-proxy can detect a
-   * re-bind to a different session and refuse stale bundles.
-   */
-  readonly allocationId: string;
-  /**
-   * Monotonic generation of the allocation binding on this worker. Fresh
-   * workers start at 1; warm-prime reserves epoch 0. A worker reused for a
-   * different allocation must receive a strictly greater epoch.
-   */
-  readonly bindingEpoch: number;
-  /**
-   * Worker-service JWT (Keycloak) — the worker's OWN egress identity,
-   * delivered into the pod via `PUT /control/service-token` and presented
-   * by the worker on its OUTBOUND calls. It is NOT the credential for
-   * inbound control-plane auth (see `workerControlPassword`). Refreshing
-   * it before expiry is the orchestrator's job; that path is NOT exposed
-   * by this runtime driver.
-   */
-  readonly workerServiceToken: string;
-  /**
-   * Per-allocation control-plane password. workspace-proxy guards every
-   * `/control/*` + `/session/*` route with HTTP Basic auth
-   * (`opencode:<password>`) seeded from its `OPENCODE_SERVER_PASSWORD`
-   * env, which the orchestrator generated for this allocation. The runtime
-   * presents it as the Basic credential on every inbound call — a JWT in a
-   * `Bearer` header is rejected by the proxy (scheme must be `Basic`).
-   */
-  readonly workerControlPassword: string;
-}
-
-/**
- * Per-runtime-instance configuration the factory accepts.
- */
-export interface OpencodeRuntimeConfig {
-  readonly workerRef: WorkerRef;
-  /**
-   * Optional caller context written into the session-bundle PUT body.
-   * The workspace-proxy bundle handler refuses calls without these
-   * three identifiers, so callers MUST provide them at runtime
-   * construction (see `BundlePayload.caller` at
-   * `biomes/workspace-proxy/api/workspace-proxy/src/handlers/control-plane.ts:818`).
-   */
-  readonly caller: BundleCallerContext;
-}
-
-/**
- * Authentication + scope context the bundle handler stamps onto the
- * worker. `authToken` is the END-USER (turn-initiator) actor JWT — the
- * service token in `WorkerRef` is presented in the HTTP Authorization
- * header, the actor JWT travels in the JSON body.
- */
-export interface BundleCallerContext {
-  readonly orgId: string;
-  readonly projectId: string;
-  readonly sessionId?: string;
-  readonly authToken: string;
-}