0xray 4.0.13 → 4.0.15

package/dist/integrations/cursor/hooks/cursor-usage-receipt.js

@@ -0,0 +1,298 @@
+/**
+ * Cursor Cloud real-usage receipt — no delegation-gate / dist required.
+ * FILL / chars÷4 is never usage proof. Host fields or Cloud MCP / dashboard only.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { buildRepertoireResume } from '../../hooks/station-hook-runtime.mjs';
+
+export const EVENT_CLASS_HOST = 'cursor-host-precompact';
+export const EVENT_CLASS_FAIL = 'cursor-host-precompact-FAIL';
+
+export const FORBIDDEN_USAGE_METHODS = new Set([
+  'chars-div-4',
+  'chars/4',
+  'chars÷4',
+  'fill-only',
+  'fill',
+  'utf8-bytes-div-4',
+  'bytes-div-4',
+]);
+
+export function invokeProbeLogPath(root) {
+  return path.join(root, '.xray', 'state', 'cursor-hook-invoke.log');
+}
+
+export function cursorUsageReceiptPath(root) {
+  return path.join(root, '.xray', 'state', 'cursor-usage-receipt.json');
+}
+
+export function parseInvokeProbeLog(root) {
+  const dest = invokeProbeLogPath(root);
+  const counts = { preToolUse: 0, preCompact: 0, afterFileEdit: 0, unknown: 0 };
+  if (!fs.existsSync(dest)) {
+    return { exists: false, path: dest, counts, hostPreCompactFired: false };
+  }
+  let text = '';
+  try {
+    text = fs.readFileSync(dest, 'utf8');
+  } catch {
+    return { exists: false, path: dest, counts, hostPreCompactFired: false };
+  }
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const match = /(?:^|\s)event=([A-Za-z]+)/.exec(line);
+    const event = match ? match[1] : 'unknown';
+    if (event === 'preToolUse') counts.preToolUse += 1;
+    else if (event === 'preCompact') counts.preCompact += 1;
+    else if (event === 'afterFileEdit') counts.afterFileEdit += 1;
+    else counts.unknown += 1;
+  }
+  return {
+    exists: true,
+    path: dest,
+    counts,
+    hostPreCompactFired: counts.preCompact > 0,
+  };
+}
+
+export function hostUsageFromPreCompactEvent(event = {}) {
+  const usage = { source: 'precompact-stdin', method: 'host-field' };
+  if (typeof event.context_tokens === 'number') usage.context_tokens = event.context_tokens;
+  if (typeof event.context_usage_percent === 'number') {
+    usage.context_usage_percent = event.context_usage_percent;
+  }
+  if (typeof event.context_window_size === 'number') {
+    usage.context_window_size = event.context_window_size;
+  }
+  if (typeof event.windowCite === 'string' && event.windowCite) usage.windowCite = event.windowCite;
+  if (typeof event.model === 'string' && event.model) usage.model = event.model;
+  if (typeof event.bcId === 'string' && event.bcId) usage.bcId = event.bcId;
+  return usage;
+}
+
+function looksLikeFillCite(cite = {}) {
+  const method = String(cite.method || '').trim().toLowerCase();
+  if (FORBIDDEN_USAGE_METHODS.has(method)) return true;
+  if (cite.fillBytes != null || cite.charsDiv4 != null || cite.fillOnly === true) return true;
+  return false;
+}
+
+function hasHostTokenFields(cite = {}) {
+  return (
+    typeof cite.context_tokens === 'number' ||
+    typeof cite.context_usage_percent === 'number' ||
+    typeof cite.context_window_size === 'number'
+  );
+}
+
+function hasMcpIdentity(cite = {}) {
+  const source = String(cite.source || '').trim();
+  if (source === 'cursor-cloud-run-info' || source === 'cursor-cloud-events' || source === 'dashboard') {
+    return true;
+  }
+  return Boolean(cite.model || cite.bcId);
+}
+
+export function classifyUsageCite(cite = {}) {
+  const method = String(cite.method || '').trim().toLowerCase();
+  const source = String(cite.source || '').trim() || null;
+  const windowCite = typeof cite.windowCite === 'string' && cite.windowCite ? cite.windowCite : null;
+  const model = typeof cite.model === 'string' && cite.model ? cite.model : null;
+  const bcId = typeof cite.bcId === 'string' && cite.bcId ? cite.bcId : null;
+  const tokens = typeof cite.context_tokens === 'number' ? cite.context_tokens : null;
+  const percent = typeof cite.context_usage_percent === 'number' ? cite.context_usage_percent : null;
+  const windowSize = typeof cite.context_window_size === 'number' ? cite.context_window_size : null;
+
+  if (looksLikeFillCite(cite)) {
+    return {
+      ok: false,
+      forbidden: true,
+      miss: false,
+      reason: 'FILL / chars÷4 is forbidden as usage proof',
+      method: method || 'fill',
+      source,
+      context_tokens: null,
+      context_usage_percent: null,
+      context_window_size: null,
+      windowCite,
+      model,
+      bcId,
+    };
+  }
+
+  if (hasHostTokenFields(cite)) {
+    return {
+      ok: true,
+      forbidden: false,
+      miss: false,
+      reason: null,
+      method: method || 'host-field',
+      source: source || 'precompact-stdin',
+      context_tokens: tokens,
+      context_usage_percent: percent,
+      context_window_size: windowSize,
+      windowCite,
+      model,
+      bcId,
+    };
+  }
+
+  if (hasMcpIdentity(cite)) {
+    return {
+      ok: true,
+      forbidden: false,
+      miss: true,
+      reason: 'MCP/dashboard identity present; token counts MISS (do not fill)',
+      method: method || source || 'mcp',
+      source,
+      context_tokens: null,
+      context_usage_percent: null,
+      context_window_size: null,
+      windowCite,
+      model,
+      bcId,
+    };
+  }
+
+  return {
+    ok: false,
+    forbidden: false,
+    miss: true,
+    reason: 'no host/MCP usage fields; do not fill',
+    method: method || null,
+    source,
+    context_tokens: null,
+    context_usage_percent: null,
+    context_window_size: null,
+    windowCite,
+    model,
+    bcId,
+  };
+}
+
+export function buildRepertoireFastenedProof(root) {
+  const resume = buildRepertoireResume(root);
+  const npmPath = path.join(root, 'node_modules', '@0xray', 'repertoire');
+  const vendorPath = path.join(root, 'vendor', '@0xray', 'repertoire');
+  const pkgFile = fs.existsSync(path.join(npmPath, 'package.json'))
+    ? path.join(npmPath, 'package.json')
+    : path.join(vendorPath, 'package.json');
+  let name = null;
+  let version = null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+    name = pkg.name || null;
+    version = pkg.version || null;
+  } catch {
+    /* organ absent */
+  }
+  const providerExists = fs.existsSync(
+    path.join(npmPath, 'dist', 'provider', 'memory-routing-provider.js'),
+  );
+  const signalsExists = fs.existsSync(path.join(npmPath, 'data', 'curated_signals.json'));
+  return {
+    fastened: name === '@0xray/repertoire' && providerExists,
+    resume,
+    name,
+    version,
+    npmPath: fs.existsSync(npmPath) ? npmPath : null,
+    vendorPath: fs.existsSync(vendorPath) ? vendorPath : null,
+    providerExists,
+    signalsExists,
+  };
+}
+
+export function buildCursorUsageReceipt(root, input = {}) {
+  const probe = parseInvokeProbeLog(root);
+  const usage = classifyUsageCite(input.usage || {});
+  const repertoire = buildRepertoireFastenedProof(root);
+  const eventClass =
+    typeof input.eventClass === 'string'
+      ? input.eventClass
+      : probe.hostPreCompactFired
+        ? EVENT_CLASS_HOST
+        : EVENT_CLASS_FAIL;
+  return {
+    ok: usage.ok && !usage.forbidden,
+    protocol: 'real-work-ab',
+    timestamp: new Date().toISOString(),
+    sessionId: input.sessionId || null,
+    compact: {
+      hostFired: probe.hostPreCompactFired,
+      preCompactCount: probe.counts.preCompact,
+      preToolUseCount: probe.counts.preToolUse,
+      afterFileEditCount: probe.counts.afterFileEdit,
+      eventClass,
+      probeLogExists: probe.exists,
+    },
+    usage,
+    repertoire,
+    hooksAtBoot: input.hooksAtBoot === true || input.hooksAtBoot === false ? input.hooksAtBoot : null,
+  };
+}
+
+function upsertStationKeyedLine(card, key, value) {
+  const line = `${key}: ${value}`;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`^${escaped}:.*$`, 'm');
+  if (re.test(card)) return card.replace(re, line);
+  const marker = 'Continue this card.';
+  const idx = card.lastIndexOf(marker);
+  if (idx >= 0) return `${card.slice(0, idx)}${line}\n\n${card.slice(idx)}`;
+  return `${card.trimEnd()}\n${line}\n`;
+}
+
+/** Host numeric window first. Ticket `windowCite` is not a substitute. Do not derive from tokens÷percent. */
+export function stationUsageWindowLabel(usage = {}) {
+  if (typeof usage.context_window_size === 'number') return String(usage.context_window_size);
+  if (typeof usage.windowCite === 'string' && usage.windowCite.trim()) return usage.windowCite.trim();
+  return 'MISS';
+}
+
+export function upsertStationCompactRow(root, receipt) {
+  const dest = path.join(root, '.xray', 'state', 'STATION.md');
+  if (!fs.existsSync(dest)) return null;
+  try {
+    const fired = receipt.compact?.hostFired ? 'Y' : 'N';
+    const count = receipt.compact?.preCompactCount ?? 0;
+    const usageBit = receipt.usage?.forbidden
+      ? 'FORBIDDEN-FILL'
+      : receipt.usage?.miss
+        ? 'MISS'
+        : 'host-field';
+    const tokens =
+      typeof receipt.usage?.context_tokens === 'number' ? String(receipt.usage.context_tokens) : 'MISS';
+    const heat = receipt.repertoire?.fastened ? 'fastened' : 'absent';
+    const windowLabel = stationUsageWindowLabel(receipt.usage || {});
+    let card = fs.readFileSync(dest, 'utf8');
+    card = upsertStationKeyedLine(
+      card,
+      'Compact',
+      `preCompact ${fired} (count=${count}) · usage ${usageBit} · repertoire ${heat}`,
+    );
+    card = upsertStationKeyedLine(
+      card,
+      'Usage',
+      `source=${receipt.usage?.source || 'none'} model=${receipt.usage?.model || 'MISS'} window=${windowLabel} tokens=${tokens}`,
+    );
+    fs.writeFileSync(dest, card);
+    return dest;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCursorUsageReceipt(root, input = {}) {
+  try {
+    const receipt = buildCursorUsageReceipt(root, input);
+    const dest = cursorUsageReceiptPath(root);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, JSON.stringify(receipt, null, 2));
+    upsertStationCompactRow(root, receipt);
+    return dest;
+  } catch {
+    return null;
+  }
+}

package/dist/integrations/cursor/hooks/hooks.json

@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/cursor/hooks/pre-tool-use.js\""
+      }
+    ],
+    "preCompact": [
+      {
+        "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/cursor/hooks/pre-compact.js\""
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "XRAY_AI_PATH=\"${XRAY_AI_PATH:-node_modules/0xray}\" node \"${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/cursor/hooks/after-file-edit.js\""
+      }
+    ]
+  }
+}

package/dist/integrations/cursor/hooks/pre-compact.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Cursor preCompact — Station writer. Observational; cannot block compaction.
+ * Host fire → event_class: cursor-host-precompact
+ * Manual/script invoke → pass --event-class=cursor-precompact-synthetic
+ */
+
+import {
+  appendHookActivity,
+  buildSessionBootPayload,
+  classifyPreCompactEvent,
+  cursorSessionId,
+  cursorWorkspaceRoot,
+  readStdinJson,
+  writeCursorPrecompactReceipt,
+  writeSessionBoot,
+} from './cursor-hook-utils.js';
+import {
+  hostUsageFromPreCompactEvent,
+  writeCursorUsageReceipt,
+} from './cursor-usage-receipt.js';
+
+function extractIntent(event) {
+  return (
+    event.prompt ||
+    event.userMessage ||
+    event.user_prompt ||
+    event.compactContext ||
+    event.user_message ||
+    null
+  );
+}
+
+async function main() {
+  const fallbackRoot = cursorWorkspaceRoot();
+  let eventClass = 'cursor-precompact-synthetic';
+  try {
+    const event = await readStdinJson();
+    eventClass = classifyPreCompactEvent(event);
+    const eventRoot = cursorWorkspaceRoot(event);
+    const sessionId = cursorSessionId(event);
+    const intent = extractIntent(event);
+    const payload = buildSessionBootPayload(eventRoot, '0xray/cursor-compact', {
+      host: 'cursor',
+      hookEvent: 'pre_compact',
+      event_class: eventClass,
+      sessionId,
+      ...(intent ? { intent } : {}),
+    });
+    const bootPath = writeSessionBoot(eventRoot, payload);
+    const receiptPath = writeCursorPrecompactReceipt(eventRoot, {
+      event_class: eventClass,
+      hookEvent: 'pre_compact',
+      trigger: event.trigger || 'synthetic',
+      sessionId,
+      bootPath,
+      timestamp: new Date().toISOString(),
+    });
+    const usagePath = writeCursorUsageReceipt(eventRoot, {
+      eventClass,
+      sessionId,
+      usage: hostUsageFromPreCompactEvent(event),
+    });
+    appendHookActivity(eventRoot, 'cursor-pre-compact', 'station-written', 'success', {
+      bootPath,
+      receiptPath,
+      usagePath,
+      event_class: eventClass,
+      stationLine: payload.stationLine,
+    });
+    console.log(
+      JSON.stringify({
+        user_message:
+          `0xRay Station written. Read .xray/state/STATION.md — do not cold-start. event_class=${eventClass}`,
+      }),
+    );
+    process.exit(0);
+  } catch (err) {
+    appendHookActivity(fallbackRoot, 'cursor-pre-compact', 'station-error', 'error', {
+      error: err.message,
+      event_class: eventClass,
+    });
+    console.log(JSON.stringify({ user_message: '0xRay Station write failed; Read STATION.md if present.' }));
+    process.exit(0);
+  }
+}
+
+main();

package/dist/integrations/cursor/hooks/pre-tool-use.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Cursor preToolUse — 0xRay constitution gate.
+ * Contract: stdin JSON → stdout {"permission":"allow"|"deny"}
+ * Does not rely on sessionStart (unavailable on managed cloud).
+ */
+
+import {
+  appendHookActivity,
+  checkCodexPatterns,
+  checkFullTestSuite,
+  cursorSessionId,
+  cursorToolContext,
+  cursorWorkspaceRoot,
+  ensureCursorSessionBoot,
+  evaluatePreToolGate,
+  isShellTool,
+  isWriteTool,
+  loadDelegationGateFeatures,
+  loadFeatures,
+  readStdinJson,
+} from './cursor-hook-utils.js';
+
+function finish(root, permission, reason, hint, toolName, extra = {}) {
+  const out = { permission };
+  if (reason) {
+    out.user_message = reason;
+    out.agent_message = reason;
+  }
+  if (hint && permission === 'allow') {
+    out.user_message = hint;
+  }
+  console.log(JSON.stringify(out));
+  appendHookActivity(root, 'cursor-pre-tool-use', permission, permission === 'deny' ? 'error' : 'info', {
+    tool: toolName,
+    reason: reason || hint || null,
+    gate: extra.gate || null,
+    livePath: true,
+  });
+  process.exit(0);
+}
+
+async function main() {
+  const fallbackRoot = cursorWorkspaceRoot();
+  let toolName = 'unknown';
+
+  try {
+    const event = await readStdinJson();
+    const eventRoot = cursorWorkspaceRoot(event);
+    ensureCursorSessionBoot(eventRoot, '0xray/cursor-pre-tool-use-boot', {
+      sessionId: cursorSessionId(event),
+    });
+
+    const features = loadFeatures(eventRoot);
+    const gateFeatures = loadDelegationGateFeatures(eventRoot, 'cursor');
+    const ctx = cursorToolContext(event);
+    toolName = ctx.toolName;
+    const { content, cmd, toolInput } = ctx;
+    const sessionId = cursorSessionId(event);
+
+    const gateBlock = evaluatePreToolGate(toolName, toolInput, {
+      projectRoot: eventRoot,
+      sessionId,
+      features: gateFeatures,
+      host: 'cursor',
+    });
+    if (!gateBlock.allow) {
+      finish(eventRoot, 'deny', gateBlock.reason, gateBlock.hint, toolName, { gate: gateBlock.gate });
+    }
+
+    if (isWriteTool(toolName) && content) {
+      const extraBlock = checkCodexPatterns(content, { terms: [11, 29] });
+      if (extraBlock) finish(eventRoot, 'deny', extraBlock, null, toolName);
+    }
+
+    if (isShellTool(toolName) && cmd) {
+      const testHint = checkFullTestSuite(cmd, features);
+      if (testHint) finish(eventRoot, 'allow', null, testHint, toolName);
+    }
+
+    if (gateBlock.reason) {
+      finish(eventRoot, 'allow', gateBlock.reason, gateBlock.hint, toolName, {
+        gate: gateBlock.gate,
+        warn: true,
+      });
+    }
+
+    finish(eventRoot, 'allow', null, null, toolName);
+  } catch (err) {
+    appendHookActivity(fallbackRoot, 'cursor-pre-tool-use', 'hook-error', 'error', {
+      tool: toolName,
+      error: err.message,
+    });
+    finish(
+      fallbackRoot,
+      'deny',
+      `preToolUse hook error — blocked for safety: ${err.message}`,
+      null,
+      toolName,
+      { gate: 'hook-error' },
+    );
+  }
+}
+
+main();

package/dist/integrations/enforcement-gate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Enforcement Gate — shared v3 pipeline entry point for TUI/CLI integration hooks.
+ *
+ * Provides beforeToolHook (early ValidatorRegistry + block decision) and
+ * afterToolHook (post-tool v3 PostProcessor loop + governance routing) that
+ * all four host integrations (OpenCode, Hermes, Grok, OpenClaw) call from
+ * their programmatic hook surfaces (tool.execute.before/after, onPreToolCall,
+ * PreToolUse, onToolBefore/onToolAfter).
+ *
+ * This is the canonical "how a TUI/CLI tool leverages v3 cleanly."
+ *
+ * @module integrations/enforcement-gate
+ */
+export interface GateViolation {
+    ruleId: string;
+    severity: string;
+    message: string;
+    suggestions?: string[];
+}
+export interface BeforeHookResult {
+    allowed: boolean;
+    blocked: boolean;
+    violations: GateViolation[];
+    resonance: number;
+    duration: number;
+}
+export interface AfterHookResult {
+    processed: boolean;
+    violations: GateViolation[];
+    processorResults: Array<{
+        name: string;
+        success: boolean;
+        error?: string;
+    }>;
+    governanceTriggered: boolean;
+    duration: number;
+}
+export interface GateContext {
+    directory?: string;
+    projectRoot?: string;
+    sessionId?: string;
+}
+export declare function beforeToolHook(tool: string, args: Record<string, unknown> | null, _context?: GateContext): Promise<BeforeHookResult>;
+export declare function afterToolHook(tool: string, args: Record<string, unknown> | null, _result: unknown, _error: string | null, _context?: GateContext): Promise<AfterHookResult>;