0xray 4.0.13 → 4.0.14

package/.opencode/skills/xray-orchestrator/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: xray-orchestrator
+description: |
+  Main orchestration skill for xray agents.
+  Provides commands to coordinate agent work and invoke xray APIs
+  through the local HTTP API server.
+metadata:
+  openclaw:
+    primaryEnv: XRAY_API_KEY
+    emoji: 🤖
+  author: xray
+  tags:
+    - ai
+    - orchestration
+    - agent
+user-invocable: true
+---
+
+# xray Orchestrator Commands
+
+## /xray
+
+Display xray status and available commands.
+
+**Usage:** `/xray`
+
+**Example:**
+```
+/xray
+```
+
+## /xray-status
+
+Get detailed status of xray integration including connection status.
+
+**Usage:** `/xray-status`
+
+**Example:**
+```
+/xray-status
+```
+
+## /xray-analyze
+
+Analyze code using xray code analysis capabilities.
+
+**Usage:** `/xray-analyze <file-path>`
+
+**Arguments:**
+- `file-path`: Path to file to analyze (required)
+
+**Example:**
+```
+/xray-analyze src/index.ts
+```
+
+## /xray-code
+
+Perform code review on a file.
+
+**Usage:** `/xray-code <file-path> [options]`
+
+**Arguments:**
+- `file-path`: Path to file to review (required)
+- `--fix`: Attempt to fix issues automatically (optional)
+
+**Example:**
+```
+/xray-code src/utils/helper.ts
+/xray-code src/utils/helper.ts --fix
+```
+
+## /xray-file
+
+Read file using xray file tools.
+
+**Usage:** `/xray-file <file-path> [line-start:line-end]`
+
+**Arguments:**
+- `file-path`: Path to file to read (required)
+- `line-start:line-end`: Line range to read (optional)
+
+**Example:**
+```
+/xray-file src/index.ts
+/xray-file src/index.ts 1:50
+```
+
+## /xray-exec
+
+Execute arbitrary xray command or script.
+
+**Usage:** `/xray-exec <command>`
+
+**Arguments:**
+- `command`: Command to execute (required)
+
+**Example:**
+```
+/xray-exec list files src/
+```
+
+## /xray-help
+
+Show this help message.
+
+**Usage:** `/xray-help [command]`
+
+**Arguments:**
+- `command`: Specific command to get help for (optional)
+
+**Example:**
+```
+/xray-help
+/xray-help xray-analyze
+```
+
+# Implementation Notes
+
+This skill acts as the main interface between OpenClaw channels and xray agents.
+It processes user commands and forwards them to the xray API server running on localhost:18431.
+
+## API Endpoints
+
+- `POST /api/agent/invoke` - Invoke xray agent
+- `GET /api/agent/status` - Get agent status
+- `GET /health` - Health check
+
+## Authentication
+
+The skill reads the `XRAY_API_KEY` environment variable for authentication.
+
+## Error Handling
+
+All errors are caught and formatted as user-friendly messages.
+Detailed error information is logged for debugging.
+
+# Dependencies
+
+- xray API server running on localhost:18431
+- XRAY_API_KEY environment variable

package/.opencode/skills/xray-orchestrator/index.ts

@@ -0,0 +1,267 @@
+/**
+ * xray Orchestrator Skill
+ *
+ * OpenClaw skill that provides xray orchestration commands.
+ *
+ * @since 2026-03-14
+ */
+
+const API_BASE = process.env.XRAY_API_URL || 'http://localhost:18431';
+const API_KEY = process.env.XRAY_API_KEY;
+
+interface ParsedArgs extends Record<string, unknown> {
+  _?: string[];
+}
+
+function parseArgs(input: string): { command: string; args: ParsedArgs } {
+  const parts = input.trim().split(/\s+/);
+  const command = parts[0] || '';
+  const args: ParsedArgs = {};
+
+  for (const part of parts.slice(1)) {
+    if (part.startsWith('--')) {
+      const key = part.slice(2);
+      args[key] = true;
+    } else if (part.includes(':')) {
+      const colonIdx = part.indexOf(':');
+      const key = part.slice(0, colonIdx);
+      const value = part.slice(colonIdx + 1);
+      if (key && value) args[key] = value;
+    } else if (!args._) {
+      args._ = [];
+      args._.push(part);
+    } else {
+      args._.push(part);
+    }
+  }
+
+  return { command, args };
+}
+
+async function callAPI(endpoint: string, data?: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+
+  if (API_KEY) {
+    headers['Authorization'] = `Bearer ${API_KEY}`;
+  }
+
+  const response = await fetch(`${API_BASE}${endpoint}`, {
+    method: data ? 'POST' : 'GET',
+    headers,
+    body: data ? JSON.stringify(data) : null,
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+    throw new Error(error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+export async function handleSkill(input: string): Promise<string> {
+  const { command, args } = parseArgs(input);
+
+  try {
+    switch (command.toLowerCase()) {
+      // xray primary
+      case 'xray':
+      case 'xray-status':
+        return await handleStatus();
+
+      case 'xray-analyze':
+        return await handleAnalyze(args);
+
+      case 'xray-code':
+        return await handleCodeReview(args);
+
+      case 'xray-file':
+        return await handleFileRead(args);
+
+      case 'xray-exec':
+        return await handleExec(args);
+
+      case 'xray-help':
+        return handleHelp(args._ as string | undefined);
+
+      default:
+        return formatHelp();
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `❌ Error: ${message}`;
+  }
+}
+
+async function handleStatus(): Promise<string> {
+  const health = await callAPI('/health') as { status: string; version: string; uptime: number };
+
+  return `🤖 xray Status
+
+• Status: ${health.status}
+• Version: ${health.version}
+• Uptime: ${formatUptime(health.uptime)}
+
+Use /xray-help for available commands.`;
+}
+
+async function handleAnalyze(args: Record<string, unknown>): Promise<string> {
+  const filePath = (args._ as string[])?.[0];
+
+  if (!filePath) {
+    return '❌ Usage: /xray-analyze <file-path>';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'analyze',
+    args: { filePath },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Analysis failed: ${result.error}`;
+  }
+
+  return `✅ Analysis complete for ${filePath}\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+async function handleCodeReview(args: Record<string, unknown>): Promise<string> {
+  const filePath = (args._ as string[])?.[0];
+  const fix = args.fix === true;
+
+  if (!filePath) {
+    return '❌ Usage: /xray-code <file-path> [--fix]';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'code-review',
+    args: { filePath, fix },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Code review failed: ${result.error}`;
+  }
+
+  return `✅ Code review complete for ${filePath}\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+async function handleFileRead(args: Record<string, unknown>): Promise<string> {
+  const rest = args._ as string[] | undefined;
+  const filePath = rest?.[0];
+  const range = rest?.[1];
+
+  if (!filePath) {
+    return '❌ Usage: /xray-file <file-path> [line-start:line-end]';
+  }
+
+  let lineRange: { start?: number; end?: number } | undefined;
+  if (range?.includes(':')) {
+    const [rawStart, rawEnd] = range.split(':');
+    lineRange = {};
+    if (rawStart) lineRange.start = Number(rawStart);
+    if (rawEnd) lineRange.end = Number(rawEnd);
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'read',
+    args: { filePath, ...lineRange },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ File read failed: ${result.error}`;
+  }
+
+  return `📄 ${filePath}\n\`\`\`\n${result.result}\n\`\`\``;
+}
+
+async function handleExec(args: Record<string, unknown>): Promise<string> {
+  const command = (args._ as string[])?.[0];
+
+  if (!command) {
+    return '❌ Usage: /xray-exec <command>';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'exec',
+    args: { command },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Execution failed: ${result.error}`;
+  }
+
+  return `✅ Command executed\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+function handleHelp(command?: string): string {
+  if (command) {
+    switch (command) {
+      case 'xray-analyze':
+        return `📖 /xray-analyze <file-path>
+
+Analyze code in a file.
+
+Example: /xray-analyze src/index.ts`;
+
+      case 'xray-code':
+        return `📖 /xray-code <file-path> [--fix]
+
+Perform code review on a file.
+Use --fix to attempt automatic fixes.
+
+Example: /xray-code src/utils/helper.ts
+Example: /xray-code src/utils/helper.ts --fix`;
+
+      case 'xray-file':
+        return `📖 /xray-file <file-path> [line-start:line-end]
+
+Read a file.
+Optionally specify line range.
+
+Example: /xray-file src/index.ts
+Example: /xray-file src/index.ts 1:50`;
+
+      case 'xray-exec':
+        return `📖 /xray-exec <command>
+
+Execute an arbitrary command.
+
+Example: /xray-exec list files src/`;
+
+      default:
+        return `Unknown command: ${command}`;
+    }
+  }
+
+  return formatHelp();
+}
+
+function formatHelp(): string {
+  return `🤖 xray Orchestrator
+
+Available Commands:
+• /xray - Show status
+• /xray-analyze <file> - Analyze code
+• /xray-code <file> [--fix] - Code review
+• /xray-file <file> [lines] - Read file
+• /xray-exec <command> - Execute command
+• /xray-help [command] - Show help
+
+Use /xray-help <command> for detailed usage.`;
+}
+
+function formatUptime(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days}d ${hours % 24}h`;
+  if (hours > 0) return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m`;
+  return `${seconds}s`;
+}
+
+// Export for OpenClaw
+export default { handleSkill };

package/.xray/features.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./features.schema.json",
-  "version": "4.0.13",
+  "version": "4.0.14",
   "description": "0xRay Framework - Unified Feature Configuration",
   "suit_temperament": {
     "profile": "auto",

package/.xray/features.schema.json

@@ -104,7 +104,7 @@
         "profile": {
           "type": "string",
           "enum": ["auto", "frontier", "guided", "strict"],
-          "description": "auto = host_defaults (grok→frontier, hermes/opencode/openclaw→guided)"
+          "description": "auto = host_defaults (grok/cursor→frontier, hermes/opencode/openclaw→guided)"
         },
         "host_defaults": {
           "type": "object",

package/AGENTS-consumer.md

@@ -19,7 +19,7 @@ Before other work, Read `.xray/state/STATION.md`. Compaction and host change are
 `npm install 0xray` runs `install-bridges.cjs` and:
 
 - Copies this file → **`AGENTS.md`** in your project root
-- Fastens mill plant (`mill` + `inspect`) then overlays **your** `src/skills` (same name wins). `npx @0xray/foundry inspect` runs the mill checks (chat is not a receipt). Does **not** dump 45/42 costume unless `foundry.json` `"costume": true`. Does **not** write root **`SKILLS.md`**
+- Fastens mill plant (`mill` + `inspect`) then overlays **your** `src/skills` (same name wins). Sound seats: `foundry.json` `"plant": "sound"` fastens `sound` + `sound-inspect` (mill off). Blip seats: `foundry.json` `"plant": "blip"` fastens `blip` + `blip-inspect` (mill off). `npx @0xray/foundry inspect` runs the mill checks; on a sound seat it also reports the last bed receipt; on a blip seat the last 4.44s receipt. Chat is not a receipt. Does **not** dump 45/42 costume unless `foundry.json` `"costume": true`. Does **not** write root **`SKILLS.md`**
 - Factory shop plant (`shop-extract`, `shop-witness`, `shop-pin` from groover-hangar) is first-class with mill plant. Extra shops: `foundry.json` `"shopPlant"`. Not costume.
 - Seeds **`.gitignore`** (from template, if absent)
 - Deploys **`.xray/`** (`codex.json`, `features.json`, `config.json`) then overlays **your** mill SSOT (`xray/codex.json`, `xray/features.json`, `src/skills`, `src/opencode/agents`; remap with `foundry.json`)
@@ -59,7 +59,9 @@ Governance deliberation uses **code-review**, **security-audit** (via enforcer/s
 | `npx 0xray codex check` | Check codex rules |
 | `npx 0xray health` | Framework health check |
 | `npx 0xray mcp <server>` | Start an MCP server (stdio) |
-| `npx @0xray/foundry inspect` | Mill inspect (nested mill). Chat is not a receipt. |
+| `npx @0xray/foundry inspect` | Mill inspect (nested mill). Sound seat: plant + last bed PASS/FAIL. Blip seat: last 4.44s PASS/FAIL. Chat is not a receipt. |
+| `npx @0xray/foundry sound render` | Factory-sound bed: brief → seed → genre → crystal mill wav → metrics receipt. |
+| `npx @0xray/foundry blip render` | Factory-blip plant: brief → seed → still\|motion:<id> → 4.44s mp4 + audio bed. Motions are Rippel v2 VisualConfig at ≥720p. Sparse seed mesh plus field accents (stars, grids, gradients, blinkers) are the NFT fingerprints. `still` is the Power Plant ident (plate dissolves, not a frozen poster). |
 
 ## Governance
 

package/AGENTS.md

@@ -43,7 +43,7 @@ Governance deliberation: **code-review**, **security-audit**, **researcher** wit
 `postinstall.cjs` → `installAllBridges()`:
 
 1. `AGENTS-consumer.md` → `AGENTS.md` (does **not** write consumer-root `SKILLS.md`)
-2. Fasten mill plant (`mill` + `inspect`). Not a 45-skill costume dump unless `foundry.json` `"costume": true`
+2. Fasten mill plant (`mill` + `inspect`). Sound seats: `foundry.json` `"plant": "sound"` fastens `sound` + `sound-inspect` and turns mill off. Blip seats: `foundry.json` `"plant": "blip"` fastens `blip` + `blip-inspect` and turns mill off. Not a 45-skill costume dump unless `foundry.json` `"costume": true`
 3. `.gitignore.default` → `.gitignore` (if absent)
 4. `.xray/` config (`codex.json`, `features.json`, `config.json`) then overlay their plant
 5. `.mcp.json` (7 servers)
@@ -52,8 +52,14 @@ Governance deliberation: **code-review**, **security-audit**, **researcher** wit
 
 **Shop plant:** `shop-extract`, `shop-witness`, `shop-pin` (groover-hangar) are first-class with mill plant. Extra shops: `foundry.json` `shopPlant`. Not `"costume": true`. `npx @0xray/foundry inspect --skip-live` is the receipt.
 
+**Sound plant:** Dist audio beds get a real plant like mill. `"plant": "sound"` + `npx @0xray/foundry sound render` writes a crystal-clear wav (Rippel membrane/metal/mixer, not a sine toy) and a bed receipt. Inspect checks loudness/smoothness gates — not fake code-mill skills on a sound seat.
+
+**Blip plant:** New factory plant sibling to mill + sound (not a mill copy). Hangar shop pair later. `"plant": "blip"` + `npx @0xray/foundry blip render --brief "..." --mode still|motion:orb` writes a 4.44s mp4 **with an audio bed**. Registry v0: still + Rippel five (`orb` `swirl` `snap` `waves` `spark`). Motions are Rippel v2 `VisualConfig.circles` at ≥720p — sharp look + tempo/frequency animation on all five (wireframe is `--engine wireframe` only). Auto bed syncopates to the motion grid. Each mint wears a sparse seed mesh plus field accents (stars, grids, gradients, blinkers); receipt `visualConfig.mesh` + `visualConfig.field` are the fingerprints. `kapow` is a growth stub. `still` is the Power Plant ident — plate dissolves over 4.44s at ≥720p (`#08090B` `#F5F7FA` `#3DE0E8` `#F5C518` `#4A7FD4`), not a frozen poster. Inspect checks duration / mode id / file / audio.
+
 ## Memory routing + Repertoire (v3.3+)
 
+**Station is the successor card** (Read `.xray/state/STATION.md`). Repertoire 0.2 is a thin routing seed (8 factory names). 0.1.0–0.1.8 were the same judgment organ; do not pin 0.1.8 for mill wear. Split: `docs-site/docs/guides/station-vs-repertoire.md`.
+
 `xray/features.json` → `memory_routing` (schema: `features.schema.json`):
 
 ```json
@@ -216,6 +222,7 @@ Full skill mapping: [SKILLS.md](SKILLS.md).
 | Platform integrations | `docs-site/docs/guides/integrations.md` |
 | Memory routing | `docs-site/docs/guides/memory-routing.md` |
 | Repertoire | `docs-site/docs/guides/repertoire.md` |
+| Station vs Repertoire 0.1 | `docs-site/docs/guides/station-vs-repertoire.md` |
 | AsideContext | `docs-site/docs/guides/aside-context.md` |
 | Consumer migration | `docs-site/docs/guides/consumer-migration.md` |
 | Docusaurus site | https://0xrayai.github.io/xray/ |

package/README.md

@@ -103,7 +103,7 @@ Docs: [guides/autonomy-command](docs-site/docs/guides/autonomy-command.md) · Sk
 On `npm install 0xray` in a consumer project, postinstall automatically:
 
 1. Copies **`AGENTS-consumer.md` → `AGENTS.md`**. Does **not** write consumer-root **`SKILLS.md`**.
-2. Fastens **mill plant** (`mill` + `inspect`). Not a 45-skill / 42-agent costume dump. `foundry.json` `"costume": true` is the opt-in dump.
+2. Fastens **mill plant** (`mill` + `inspect`). Sound seats: `foundry.json` `"plant": "sound"` fastens the bed factory (`sound` + `sound-inspect`) and turns mill off. Blip seats: `foundry.json` `"plant": "blip"` fastens the tiny-video factory (`blip` + `blip-inspect`) and turns mill off. Not a 45-skill / 42-agent costume dump. `foundry.json` `"costume": true` is the opt-in dump.
 3. Seeds **`.gitignore`** from `.gitignore.default` (if absent)
 4. Deploys **`.xray/`** config (`codex.json`, `features.json`, `config.json`) then overlays **their** plant
 5. Writes project **`.mcp.json`** with 7 MCPs servers (`npx -y 0xray mcp …`)

package/SKILLS.md

@@ -2,7 +2,7 @@
 
 **4.0** — a suit that survives the context window
 
-**45 skills** in this exo catalog. Default consumer plant is **`mill` + `inspect`**, not this dump. `npm install 0xray` does **not** sync 45 skills unless `foundry.json` `"costume": true`. Factory shop plant (`shop-extract`, `shop-witness`, `shop-pin`) coexists with mill plant when a hangar wears those shops. Extra shops: `foundry.json` `shopPlant`. Agent map: [llms.txt](llms.txt).
+**45 skills** in this exo catalog. Default consumer plant is **`mill` + `inspect`**, not this dump. `npm install 0xray` does **not** sync 45 skills unless `foundry.json` `"costume": true`. Factory shop plant (`shop-extract`, `shop-witness`, `shop-pin`) coexists with mill plant when a hangar wears those shops. Extra shops: `foundry.json` `shopPlant`. Sound seats: `foundry.json` `"plant": "sound"` (foundry plant, not this catalog). Blip seats: `foundry.json` `"plant": "blip"` (foundry plant, not this catalog). Agent map: [llms.txt](llms.txt).
 
 xray ships 45 knowledge skills (`src/skills/<name>/SKILL.md`) as the **costume / self-plant catalog**. Lead-dev operating model lives in **`orchestrator`** skill + `multi_agent_orchestration.lead_dev_mode` in features.json. Skills load on demand via the **xray-skills** MCP server (`npx -y 0xray mcp skills`) or when you plant them. This file is the exo catalog — mill does **not** write it to the consumer root.
 

package/dist/.gitignore.default

@@ -0,0 +1,67 @@
+# 0xray — Default .gitignore
+# Generated by 0xray postinstall. Edit as needed.
+
+# Dependencies
+node_modules/
+
+# Build artifacts
+dist/
+build/
+*.tsbuildinfo
+
+# Environment & secrets
+.env
+.env.*
+.env.local
+*.local
+**/auth.json
+.hermes/
+credentials.json
+*.pem
+*.key
+
+# 0xray suit artifacts (postinstall / bridge install)
+.grok/
+.mcp.json
+opencode.json
+AGENTS.md
+SKILLS.md
+
+# Runtime state (xray inference workflows, session state)
+.xray/
+.strray/
+strray/
+xray/inference/
+
+# Generated xray config files
+.opencode/agents/*.yml
+.opencode/agents/
+.opencode/commands/
+.opencode/workflows/
+.opencode/codex.codex
+.opencode/enforcer-config.json
+.opencode/skills/
+.opencode/scripts/
+.opencode/logs/
+.opencode/validation/
+.opencode/triage/
+
+# Logs
+logs/
+logs/framework/
+*.log
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Temp
+*.tmp
+*.tgz