0xray 4.0.13 → 4.0.15

package/dist/integrations/base/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Integration Base Types
+ *
+ * Common TypeScript interfaces for 0xRay integrations.
+ * Provides a standardized foundation for all integration types.
+ *
+ * @since 2026-03-15
+ */
+import type { EventEmitter } from "events";
+/**
+ * Log levels for integration logging
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+/**
+ * Integration configuration options
+ */
+export interface IntegrationConfig {
+    /** Whether the integration is enabled */
+    enabled: boolean;
+    /** Enable debug mode for additional logging */
+    debug: boolean;
+    /** Log level for the integration */
+    logLevel: LogLevel;
+    /** Optional custom configuration options */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Default integration configuration
+ */
+export declare const DEFAULT_INTEGRATION_CONFIG: IntegrationConfig;
+/**
+ * Integration lifecycle status
+ */
+export type IntegrationStatus = "uninitialized" | "initializing" | "initialized" | "error" | "shutting-down" | "shutdown";
+/**
+ * Health check result
+ */
+export interface HealthResult {
+    /** Whether the integration is healthy */
+    healthy: boolean;
+    /** Human-readable message describing the health status */
+    message: string;
+    /** Optional additional details about the health status */
+    details?: Record<string, unknown> | undefined;
+}
+/**
+ * Default healthy result
+ */
+export declare const HEALTHY_RESULT: HealthResult;
+/**
+ * Default unhealthy result
+ */
+export declare function createUnhealthyResult(message: string, details?: Record<string, unknown>): HealthResult;
+/**
+ * Base integration statistics
+ */
+export interface IntegrationStats {
+    /** Time since initialization in milliseconds */
+    uptime: number;
+    /** Number of errors encountered */
+    errors: number;
+    /** Optional custom statistics */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Creates a default integration stats object
+ */
+export declare function createIntegrationStats(): IntegrationStats;
+/**
+ * Base integration events
+ */
+export type IntegrationEventType = "initialized" | "initializing" | "shutdown" | "shutting-down" | "error" | "health-check" | "stats-updated" | "config-updated";
+/**
+ * Integration event payload
+ */
+export interface IntegrationEvent<T = unknown> {
+    /** Event type */
+    type: IntegrationEventType;
+    /** Timestamp when the event occurred */
+    timestamp: number;
+    /** Event data */
+    data?: T | undefined;
+    /** Optional error if event represents an error */
+    error?: Error | undefined;
+}
+/**
+ * Integration interface
+ * All 0xRay integrations must implement this interface
+ */
+export interface IIntegration {
+    /** Unique name of the integration */
+    readonly name: string;
+    /** Version of the integration */
+    readonly version: string;
+    /** Current lifecycle status */
+    readonly status: IntegrationStatus;
+    /**
+     * Initialize the integration with optional configuration
+     * @param config - Optional partial configuration to merge with defaults
+     */
+    initialize(config?: Partial<IntegrationConfig>): Promise<void>;
+    /**
+     * Gracefully shutdown the integration
+     * Should clean up resources and close connections
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Perform a health check
+     * @returns Promise resolving to health result
+     */
+    healthCheck(): Promise<HealthResult>;
+    /**
+     * Get current integration statistics
+     * @returns Current stats object
+     */
+    getStats(): IntegrationStats;
+}
+/**
+ * Extended integration interface with event support
+ */
+export interface IEventedIntegration extends IIntegration {
+    /** Get the event emitter for this integration */
+    getEventEmitter(): EventEmitter;
+}
+/**
+ * Integration factory function type
+ */
+export type IntegrationFactory<T extends IIntegration = IIntegration> = (config?: Partial<IntegrationConfig>) => T;
+/**
+ * Integration constructor type
+ */
+export type IntegrationConstructor<T extends IIntegration = IIntegration> = new (config?: Partial<IntegrationConfig>) => T;
+/**
+ * Base error class for integration errors
+ */
+export declare class IntegrationError extends Error {
+    readonly code: string;
+    readonly recoverable: boolean;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, recoverable: boolean, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when integration is not initialized
+ */
+export declare class IntegrationNotInitializedError extends IntegrationError {
+    constructor(integrationName: string);
+}
+/**
+ * Error thrown when integration is already initialized
+ */
+export declare class IntegrationAlreadyInitializedError extends IntegrationError {
+    constructor(integrationName: string);
+}
+/**
+ * Error thrown during integration initialization
+ */
+export declare class IntegrationInitializationError extends IntegrationError {
+    constructor(integrationName: string, originalError: Error);
+}
+/**
+ * Type guard to check if an object is an integration
+ */
+export declare function isIntegration(value: unknown): value is IIntegration;
+/**
+ * Type guard to check if an object is a health result
+ */
+export declare function isHealthy(result: HealthResult): boolean;

package/dist/integrations/base/types.js

@@ -0,0 +1,117 @@
+/**
+ * Integration Base Types
+ *
+ * Common TypeScript interfaces for 0xRay integrations.
+ * Provides a standardized foundation for all integration types.
+ *
+ * @since 2026-03-15
+ */
+/**
+ * Default integration configuration
+ */
+export const DEFAULT_INTEGRATION_CONFIG = {
+    enabled: true,
+    debug: false,
+    logLevel: "info",
+};
+/**
+ * Default healthy result
+ */
+export const HEALTHY_RESULT = {
+    healthy: true,
+    message: "Integration is healthy",
+};
+/**
+ * Default unhealthy result
+ */
+export function createUnhealthyResult(message, details) {
+    if (details && Object.keys(details).length > 0) {
+        return {
+            healthy: false,
+            message,
+            details,
+        };
+    }
+    return {
+        healthy: false,
+        message,
+    };
+}
+/**
+ * Creates a default integration stats object
+ */
+export function createIntegrationStats() {
+    return {
+        uptime: 0,
+        errors: 0,
+    };
+}
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * Base error class for integration errors
+ */
+export class IntegrationError extends Error {
+    code;
+    recoverable;
+    context;
+    constructor(message, code, recoverable, context) {
+        super(message);
+        this.code = code;
+        this.recoverable = recoverable;
+        this.context = context;
+        this.name = "IntegrationError";
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * Error thrown when integration is not initialized
+ */
+export class IntegrationNotInitializedError extends IntegrationError {
+    constructor(integrationName) {
+        super(`Integration '${integrationName}' is not initialized. Call initialize() first.`, "NOT_INITIALIZED", false, { integrationName });
+        this.name = "IntegrationNotInitializedError";
+    }
+}
+/**
+ * Error thrown when integration is already initialized
+ */
+export class IntegrationAlreadyInitializedError extends IntegrationError {
+    constructor(integrationName) {
+        super(`Integration '${integrationName}' is already initialized.`, "ALREADY_INITIALIZED", false, { integrationName });
+        this.name = "IntegrationAlreadyInitializedError";
+    }
+}
+/**
+ * Error thrown during integration initialization
+ */
+export class IntegrationInitializationError extends IntegrationError {
+    constructor(integrationName, originalError) {
+        super(`Failed to initialize integration '${integrationName}': ${originalError.message}`, "INITIALIZATION_FAILED", true, { integrationName, originalError: originalError.message });
+        this.name = "IntegrationInitializationError";
+    }
+}
+// ============================================================================
+// Utility Types
+// ============================================================================
+/**
+ * Type guard to check if an object is an integration
+ */
+export function isIntegration(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "name" in value &&
+        "version" in value &&
+        "status" in value &&
+        "initialize" in value &&
+        "shutdown" in value &&
+        "healthCheck" in value &&
+        "getStats" in value);
+}
+/**
+ * Type guard to check if an object is a health result
+ */
+export function isHealthy(result) {
+    return result.healthy === true;
+}

package/dist/integrations/cursor/README.md

@@ -0,0 +1,61 @@
+# Cursor cloud hooks (0xRay)
+
+Thin adapter. Repo `.cursor/hooks.json` (schema **version 1**) calls 0xRay gates and the Station PreCompact writer. **sessionStart is not used** — managed Cursor cloud does not fire it.
+
+Repertoire MCP is optional. Station + gates work without a full memory-routing rewire.
+
+## How cloud picks up project hooks
+
+1. Commit `.cursor/hooks.json` at the **project root** (this file, not `~/.cursor/hooks.json`).
+2. Cursor Cloud Agent clones the repo and loads **project** hooks. Desktop Agent Chat does the same when the folder is the workspace.
+3. Hook names are camelCase: `preToolUse`, `preCompact`, `afterFileEdit`. Commands are shell strings. Stdin is JSON; stdout is JSON.
+4. First `preToolUse` or `afterFileEdit` writes `.xray/state/session-boot.json` + `.xray/state/STATION.md`. After a compact, **Read STATION.md**. The host does not inject it.
+5. `preCompact` is observational (cannot block). It merges Station (stock heat updates; ticket / seed / Durable / unfinished keys stay).
+
+Copy the consumer template from `src/integrations/cursor/hooks/hooks.json` (dist paths under `node_modules/0xray`) when wearing the published package. This exo repo wears `src/integrations/cursor/hooks/*.js` so a cloud can run before `npm run build`.
+
+## Contracts
+
+| Hook | Stdin | Stdout |
+|------|--------|--------|
+| `preToolUse` | Cursor tool event (`tool_name`, `tool_input`, `cwd`, `workspace_roots`, `conversation_id`) | `{ "permission": "allow" \| "deny" }` plus `user_message` / `agent_message` on deny |
+| `preCompact` | `{ trigger, context_tokens, … }` | `{ "user_message": "…" }` after Station write |
+| `afterFileEdit` | file event | `{}` — boots Station only |
+
+`preCompact` labels `event_class`:
+
+- `cursor-host-precompact` — Cursor actually fired the hook
+- `cursor-precompact-synthetic` — script invoked with `--event-class=cursor-precompact-synthetic` (Path C fallback)
+- `cursor-host-precompact-FAIL` — HOST-FIRE fill ran; host did not spawn `preCompact` (see `RECEIPT-HOST-PRECOMPACT.md`, `-2.md`, `-3.md`)
+- First live host fire (Arm S): `examples/killer-dual/RECEIPT-HOST-PRECOMPACT.md`
+
+## Real usage (replace FILL)
+
+Do **not** prove window pressure with UTF-8 chars÷4. `src/integrations/cursor/hooks/cursor-usage-receipt.js` (`writeCursorUsageReceipt`) writes `.xray/state/cursor-usage-receipt.json` + Station `Compact:` / `Usage:` rows. Station `window=` prints host `context_window_size` when stdin sent it; ticket `windowCite` is fallback only. No `dist` required (unlike the constitution gate).
+
+| Cite | Valid? |
+|------|--------|
+| `preCompact` stdin `context_tokens` / `context_usage_percent` / `context_window_size` | yes |
+| `cursor-cloud` `run-info` / `get-events` / dashboard (model, bc-id, window) | yes — token MISS is honest |
+| chars÷4, fill-only, `fillBytes` | **forbidden** (`ok: false`) |
+
+Host `preCompact` fire is counted from `.xray/state/cursor-hook-invoke.log` (`event=preCompact`). Do not hand-invoke `pre-compact.js` to mint that Y.
+
+Arm S landscape + receipt: `examples/killer-dual/`.
+
+## Friend test
+
+From the repo root, after `npm run build` (or from `src/` on this exo):
+
+```bash
+echo '{"tool_name":"Read","tool_input":{"path":"README.md"},"cwd":"'"$PWD"'"}' \
+  | node src/integrations/cursor/hooks/pre-tool-use.js
+# → {"permission":"allow"}
+
+echo '{"hook_event_name":"preCompact","trigger":"auto","context_tokens":1}' \
+  | node src/integrations/cursor/hooks/pre-compact.js --event-class=cursor-precompact-synthetic
+# → user_message includes event_class=cursor-precompact-synthetic
+# → Read .xray/state/STATION.md
+```
+
+Path C seed + receipt: `examples/cursor-cloud-compact/`. Suited Arm S (real usage, no FILL): `examples/killer-dual/`.

package/dist/integrations/cursor/hooks/after-file-edit.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * Cursor afterFileEdit — boot Station when sessionStart did not fire.
+ * Observational; file already written.
+ */
+
+import {
+  appendHookActivity,
+  cursorSessionId,
+  cursorWorkspaceRoot,
+  ensureCursorSessionBoot,
+  readStdinJson,
+} from './cursor-hook-utils.js';
+
+async function main() {
+  const fallbackRoot = cursorWorkspaceRoot();
+  try {
+    const event = await readStdinJson();
+    const eventRoot = cursorWorkspaceRoot(event);
+    const bootPath = ensureCursorSessionBoot(eventRoot, '0xray/cursor-after-file-edit-boot', {
+      sessionId: cursorSessionId(event),
+    });
+    appendHookActivity(eventRoot, 'cursor-after-file-edit', 'session-boot', 'info', {
+      bootPath,
+      file: event.file_path || event.path || null,
+    });
+    console.log(JSON.stringify({}));
+    process.exit(0);
+  } catch (err) {
+    appendHookActivity(fallbackRoot, 'cursor-after-file-edit', 'hook-error', 'error', {
+      error: err.message,
+    });
+    console.log(JSON.stringify({}));
+    process.exit(0);
+  }
+}
+
+main();

package/dist/integrations/cursor/hooks/cursor-hook-utils.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * Cursor cloud hook utilities — normalize host stdin, reuse 0xRay gate + Station.
+ * sessionStart is unavailable on managed cloud; first preToolUse / afterFileEdit boots.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {
+  buildSessionBootPayload,
+  writeSessionBoot,
+  readStdinJson,
+  loadFeatures,
+  checkCodexPatterns,
+  checkFullTestSuite,
+  isWriteTool,
+  isShellTool,
+  sessionBootPath,
+} from '../../grok/hooks/grok-hook-utils.js';
+import {
+  evaluatePreToolGate,
+  loadDelegationGateFeatures,
+} from '../../hooks/delegation-gate-runtime.mjs';
+import { appendHookActivity } from '../../grok/hooks/grok-hook-activity.js';
+import {
+  buildRepertoireResume,
+  readGitBrief,
+} from '../../hooks/station-hook-runtime.mjs';
+
+export const CURSOR_HOST = 'cursor';
+export const EVENT_CLASS_HOST = 'cursor-host-precompact';
+export const EVENT_CLASS_SYNTHETIC = 'cursor-precompact-synthetic';
+
+export {
+  readStdinJson,
+  writeSessionBoot,
+  buildSessionBootPayload,
+  loadFeatures,
+  checkCodexPatterns,
+  checkFullTestSuite,
+  isWriteTool,
+  isShellTool,
+  sessionBootPath,
+  evaluatePreToolGate,
+  loadDelegationGateFeatures,
+  appendHookActivity,
+};
+
+export {
+  FORBIDDEN_USAGE_METHODS,
+  invokeProbeLogPath,
+  cursorUsageReceiptPath,
+  parseInvokeProbeLog,
+  hostUsageFromPreCompactEvent,
+  classifyUsageCite,
+  buildRepertoireFastenedProof,
+  buildCursorUsageReceipt,
+  upsertStationCompactRow,
+  writeCursorUsageReceipt,
+} from './cursor-usage-receipt.js';
+
+export function cursorWorkspaceRoot(event = {}) {
+  const roots = event.workspace_roots || event.workspaceRoots;
+  const fromList = Array.isArray(roots) && roots[0] ? String(roots[0]) : '';
+  return (
+    event.cwd ||
+    event.workspaceRoot ||
+    fromList ||
+    process.env.CURSOR_PROJECT_DIR ||
+    process.env.XRAY_ROOT ||
+    process.env.GROK_WORKSPACE_ROOT ||
+    process.cwd()
+  );
+}
+
+export function cursorSessionId(event = {}) {
+  return (
+    event.conversation_id ||
+    event.session_id ||
+    event.sessionId ||
+    process.env.CURSOR_CONVERSATION_ID ||
+    process.env.CURSOR_SESSION_ID ||
+    null
+  );
+}
+
+export function cursorToolContext(event = {}) {
+  const toolName = event.tool_name || event.toolName || process.env.TOOL_NAME || 'unknown';
+  const toolInput = event.tool_input ?? event.toolInput ?? {};
+  const paths = [];
+  let content = '';
+
+  if (toolInput.path) paths.push(String(toolInput.path));
+  if (toolInput.file_path) paths.push(String(toolInput.file_path));
+  if (toolInput.target_notebook) paths.push(String(toolInput.target_notebook));
+  if (Array.isArray(toolInput.paths)) paths.push(...toolInput.paths.map(String));
+
+  if (toolInput.new_string) content += String(toolInput.new_string);
+  if (toolInput.contents) content += String(toolInput.contents);
+  if (toolInput.command) content += String(toolInput.command);
+  if (toolInput.prompt) content += String(toolInput.prompt);
+
+  return {
+    toolName,
+    toolInput,
+    paths,
+    content,
+    cmd: String(toolInput.command || event.command || ''),
+  };
+}
+
+function namedEventClass(value) {
+  if (value === EVENT_CLASS_HOST || value === EVENT_CLASS_SYNTHETIC) return value;
+  return null;
+}
+
+export function classifyPreCompactEvent(event = {}, argv = process.argv) {
+  const fromEnv = namedEventClass(process.env.XRAY_CURSOR_COMPACT_CLASS);
+  if (fromEnv) return fromEnv;
+  const flag = argv.find((a) => a.startsWith('--event-class='));
+  if (flag) {
+    const fromArg = namedEventClass(flag.slice('--event-class='.length));
+    if (fromArg) return fromArg;
+  }
+  const fromEvent = namedEventClass(event.event_class);
+  if (fromEvent) return fromEvent;
+
+  const named = event.hook_event_name || event.hookEventName || event.hook;
+  const looksHost =
+    named === 'preCompact' ||
+    named === 'pre_compact' ||
+    event.trigger === 'auto' ||
+    event.trigger === 'manual' ||
+    typeof event.context_tokens === 'number' ||
+    typeof event.context_usage_percent === 'number';
+  return looksHost ? EVENT_CLASS_HOST : EVENT_CLASS_SYNTHETIC;
+}
+
+export function cursorBootNeedsRefresh(existing, root) {
+  if (!existing || typeof existing !== 'object') return true;
+  if (existing.host !== CURSOR_HOST) return true;
+  if (!existing.suit_profile) return true;
+  if (existing.workspaceRoot && existing.workspaceRoot !== root) return true;
+  if (!existing.stationLine) return true;
+  const liveGit = readGitBrief(root);
+  const bootHead = existing.git && existing.git.head ? String(existing.git.head) : '';
+  if (liveGit && liveGit.head && bootHead !== liveGit.head) return true;
+  const liveResume = buildRepertoireResume(root);
+  if (liveResume && existing.repertoireResume && liveResume !== existing.repertoireResume) return true;
+  return false;
+}
+
+export function ensureCursorSessionBoot(root, source = '0xray/cursor-pre-tool-use-boot', extra = {}) {
+  const bootPath = sessionBootPath(root);
+  if (fs.existsSync(bootPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(bootPath, 'utf8'));
+      if (!cursorBootNeedsRefresh(existing, root)) return bootPath;
+    } catch {
+      /* rewrite corrupt or host-mismatched boot */
+    }
+  }
+  const payload = buildSessionBootPayload(root, source, {
+    host: CURSOR_HOST,
+    ...extra,
+  });
+  return writeSessionBoot(root, payload) || bootPath;
+}
+
+export function writeCursorPrecompactReceipt(root, fields) {
+  try {
+    const dest = path.join(root, '.xray', 'state', 'cursor-precompact.json');
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, JSON.stringify(fields, null, 2));
+    return dest;
+  } catch {
+    return null;
+  }
+}