@stackwright-pro/otters 1.0.0-alpha.3 → 1.0.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,7 @@
     "url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
   },
   "devDependencies": {
-    "vitest": "^1.4.0",
+    "vitest": "^4.0.18",
     "zod": "^3.22.4"
   },
   "exports": {
@@ -19,8 +19,11 @@
     "scripts",
     "src"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependencies": {
-    "@stackwright-pro/mcp": "0.2.0-alpha.0"
+    "@stackwright-pro/mcp": "^0.2.0-alpha.1"
   },
   "scripts": {
     "generate-checksums": "node scripts/generate-checksums.js",

package/src/python-bridge.ts

@@ -0,0 +1,391 @@
+/**
+ * Python Bridge - Spawns Python server and communicates via JSON over stdio
+ *
+ * This module provides the interface between Node.js CLI and the Python
+ * Clarification Protocol server.
+ *
+ * Architecture:
+ * - Node.js CLI spawns Python server (unix socket + HTTP)
+ * - Communication via JSON over stdio or HTTP
+ * - Supports both blocking (TUI) and non-blocking (API) modes
+ */
+
+import { spawn, ChildProcess, execSync } from 'child_process';
+import { existsSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+// Types
+export interface ClarificationRequest {
+  context: string;
+  question_type: 'closed_choice' | 'open_text' | 'conditional' | 'multi_step' | 'reconciliation';
+  question: string;
+  choices?: string[];
+  priority?: 'blocking' | 'preferred' | 'optional';
+  target_field?: string;
+  partial_result?: Record<string, unknown>;
+}
+
+export interface ClarificationResponse {
+  request_id: string;
+  decision: {
+    value: unknown;
+    explicit: boolean;
+    source: string;
+  };
+  fallback_used: boolean;
+  fallback_reason?: string;
+}
+
+export interface ConflictCheck {
+  stated_preference: string;
+  selected_values: Record<string, string>;
+}
+
+export interface ConflictResult {
+  conflict: boolean;
+  data?: {
+    description: string;
+    stated: string;
+    options: string[];
+  };
+}
+
+export interface SessionInfo {
+  id: string;
+  phase: string;
+  context: Record<string, unknown>;
+}
+
+// Constants
+const DEFAULT_SOCKET_PATH = join(tmpdir(), `otter-raft-${randomUUID()}.sock`);
+const DEFAULT_HTTP_PORT = 8765;
+
+/**
+ * PythonBridge - Communicates with Python Clarification Protocol server
+ */
+export class PythonBridge {
+  private socketPath: string;
+  private httpPort: number;
+  private pythonProcess: ChildProcess | null = null;
+  private useHttp: boolean;
+  private baseUrl: string;
+
+  constructor(options?: { socketPath?: string; httpPort?: number }) {
+    this.socketPath = options?.socketPath || DEFAULT_SOCKET_PATH;
+    this.httpPort = options?.httpPort || DEFAULT_HTTP_PORT;
+    this.useHttp = true; // Prefer HTTP for reliability
+    this.baseUrl = `http://127.0.0.1:${this.httpPort}`;
+  }
+
+  /**
+   * Start the Python server
+   */
+  async start(): Promise<void> {
+    // Find Python executable
+    const pythonPath = this.findPython();
+
+    // Find the Python package
+    const packageRoot = this.findPackageRoot();
+    const serverModule = 'stackwright_pro.raft.server';
+
+    return new Promise((resolve, reject) => {
+      // Clean up old socket
+      if (existsSync(this.socketPath)) {
+        try {
+          unlinkSync(this.socketPath);
+        } catch {
+          // Ignore
+        }
+      }
+
+      this.pythonProcess = spawn(
+        pythonPath,
+        ['-m', serverModule, '--socket', this.socketPath, '--port', String(this.httpPort)],
+        {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: {
+            ...process.env,
+            PYTHONPATH: packageRoot,
+          },
+        }
+      );
+
+      let startupOutput = '';
+
+      this.pythonProcess.stdout?.on('data', (data: Buffer) => {
+        startupOutput += data.toString();
+        // Look for "Server ready" message
+        if (startupOutput.includes('Server ready') || startupOutput.includes('Starting')) {
+          // Give it a moment to fully start
+          setTimeout(() => resolve(), 500);
+        }
+      });
+
+      this.pythonProcess.stderr?.on('data', (data: Buffer) => {
+        console.error('[Python]', data.toString().trim());
+      });
+
+      this.pythonProcess.on('error', (err) => {
+        reject(new Error(`Failed to start Python server: ${err.message}`));
+      });
+
+      this.pythonProcess.on('exit', (code) => {
+        if (code !== 0 && code !== null) {
+          reject(new Error(`Python server exited with code ${code}`));
+        }
+      });
+
+      // Timeout after 10 seconds
+      setTimeout(() => {
+        reject(new Error('Python server startup timeout'));
+      }, 10000);
+    });
+  }
+
+  /**
+   * Stop the Python server
+   */
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.pythonProcess) {
+        this.pythonProcess.on('exit', () => resolve());
+        this.pythonProcess.kill('SIGTERM');
+
+        // Force kill after 5 seconds
+        setTimeout(() => {
+          if (this.pythonProcess) {
+            this.pythonProcess.kill('SIGKILL');
+          }
+          resolve();
+        }, 5000);
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  /**
+   * Health check
+   */
+  async health(): Promise<{ status: string; version: string }> {
+    return this.httpRequest('/health');
+  }
+
+  /**
+   * Create a new clarification session
+   */
+  async createSession(): Promise<{ session_id: string }> {
+    return this.httpRequest('/sessions', {
+      method: 'POST',
+    });
+  }
+
+  /**
+   * Get session info
+   */
+  async getSession(sessionId: string): Promise<SessionInfo> {
+    return this.httpRequest(`/sessions/${sessionId}`);
+  }
+
+  /**
+   * Set session phase
+   */
+  async setPhase(sessionId: string, phase: string): Promise<{ phase: string }> {
+    return this.httpRequest(`/sessions/${sessionId}/phase`, {
+      method: 'POST',
+      body: { phase },
+    });
+  }
+
+  /**
+   * Update session context
+   */
+  async updateContext(
+    sessionId: string,
+    context: Record<string, unknown>
+  ): Promise<{ context: Record<string, unknown> }> {
+    return this.httpRequest(`/sessions/${sessionId}/context`, {
+      method: 'POST',
+      body: { context },
+    });
+  }
+
+  /**
+   * Ask for clarification within a session
+   */
+  async sessionClarify(
+    sessionId: string,
+    request: ClarificationRequest
+  ): Promise<ClarificationResponse> {
+    return this.httpRequest(`/sessions/${sessionId}/clarify`, {
+      method: 'POST',
+      body: { request },
+    });
+  }
+
+  /**
+   * Quick clarify (no session)
+   */
+  async clarify(request: ClarificationRequest): Promise<ClarificationResponse> {
+    return this.httpRequest('/clarify', {
+      method: 'POST',
+      body: { request },
+    });
+  }
+
+  /**
+   * Detect preference conflict
+   */
+  async detectConflict(check: ConflictCheck): Promise<ConflictResult> {
+    return this.httpRequest('/conflict', {
+      method: 'POST',
+      body: check,
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  // Private methods
+  // --------------------------------------------------------------------------
+
+  private findPython(): string {
+    // Try python3 first, fall back to python
+    try {
+      execSync('python3 --version', { stdio: 'pipe' });
+      return 'python3';
+    } catch {
+      return 'python';
+    }
+  }
+
+  private findPackageRoot(): string {
+    // Look for the Python package in common locations
+    const candidates = [
+      join(__dirname, '../../python/src'),
+      join(__dirname, '../../../python/src'),
+      join(process.cwd(), 'python/src'),
+    ];
+
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    // Default to current directory
+    return process.cwd();
+  }
+
+  private async httpRequest<T>(
+    path: string,
+    options?: {
+      method?: string;
+      body?: unknown;
+    }
+  ): Promise<T> {
+    const http = await import('http');
+
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, this.baseUrl);
+
+      const reqOptions = {
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname,
+        method: options?.method || 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      };
+
+      const req = http.request(reqOptions, (res) => {
+        let data = '';
+
+        res.on('data', (chunk: Buffer) => {
+          data += chunk.toString();
+        });
+
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+
+            if (res.statusCode && res.statusCode >= 400) {
+              reject(new Error(parsed.detail || parsed.error || `HTTP ${res.statusCode}`));
+            } else {
+              resolve(parsed);
+            }
+          } catch (e) {
+            reject(new Error(`Failed to parse response: ${data}`));
+          }
+        });
+      });
+
+      req.on('error', (e) => {
+        reject(new Error(`HTTP request failed: ${e.message}`));
+      });
+
+      if (options?.body) {
+        req.write(JSON.stringify(options.body));
+      }
+
+      req.end();
+    });
+  }
+}
+
+/**
+ * Create a bridge instance and auto-start it
+ */
+export async function createBridge(options?: {
+  socketPath?: string;
+  httpPort?: number;
+}): Promise<PythonBridge> {
+  const bridge = new PythonBridge(options);
+  await bridge.start();
+  return bridge;
+}
+
+/**
+ * Run a single clarification in stdio mode (no server)
+ *
+ * Usage:
+ *   echo '{"type":"clarify","request":{...}}' | python -m stackwright_pro.raft.server --stdio
+ */
+export async function runStdioClarify(
+  request: ClarificationRequest
+): Promise<ClarificationResponse> {
+  const http = await import('http');
+
+  // For stdio mode, we communicate directly via stdin/stdout
+  // This is handled by the Python server in --stdio mode
+  return new Promise((resolve, reject) => {
+    const input = JSON.stringify({
+      type: 'clarify',
+      request,
+    });
+
+    const proc = spawn('python', ['-m', 'stackwright_pro.raft.server', '--stdio'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let output = '';
+
+    proc.stdout?.on('data', (data: Buffer) => {
+      output += data.toString();
+    });
+
+    proc.on('close', () => {
+      try {
+        resolve(JSON.parse(output));
+      } catch {
+        reject(new Error(`Failed to parse response: ${output}`));
+      }
+    });
+
+    proc.on('error', reject);
+
+    proc.stdin?.write(input);
+    proc.stdin?.end();
+  });
+}