kroki 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# Kroki CLI
+
+> **Browser Automation & AI Agent Bridge for Google Chrome & Dolphin{anty}**  
+> Control live browser tabs, run deterministic workflows, and extract web data from your terminal or any AI Coding Agent (Antigravity, Cursor, Claude Code, Windsurf).
+
+[![npm version](https://img.shields.io/npm/v/kroki.svg)](https://www.npmjs.com/package/kroki)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node: >=18](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+---
+
+## ⚡ Quick Start
+
+No installation required. You can run it directly with `npx`:
+
+### 1. Pair with your browser profile
+
+Go to your [Kroki Devices Dashboard](https://kroki.one/devices) and click **"Скопировать код для AI"** next to the active Chrome or Dolphin{anty} profile you want to control.
+
+```bash
+npx kroki pair <YOUR_PAIRING_CODE>
+```
+
+```text
+Connecting to profile [Dolphin WB-Bot]...
+✔ Successfully paired with "Dolphin WB-Bot".
+```
+
+### 2. Send an AI task to the live browser
+
+```bash
+npx kroki "open wildberries.ru, search for 'iPhone 16 cases' and list the top 5 prices"
+```
+
+Kroki's built-in Planner & Navigator subagent will navigate to the page, interact with elements, extract the requested information, and stream the result back to your terminal.
+
+### 3. Run a saved workflow
+
+```bash
+npx kroki run "Export Leads" '{"query": "CTO", "limit": 20}'
+```
+
+---
+
+## 📦 Global Installation (Optional)
+
+If you prefer using `kroki` without typing `npx` every time:
+
+```bash
+npm install -g kroki
+```
+
+Now you can just run:
+
+```bash
+kroki pair <CODE>
+kroki "scrape the current page"
+kroki run "My Workflow"
+```
+
+---
+
+## 🤖 Using with AI Agents (Antigravity, Claude Code, Cursor)
+
+Kroki CLI works out-of-the-box with AI pair-programming agents.
+
+### In Antigravity CLI
+
+Whenever you mention **kroki** in the chat, the agent automatically knows how to use this CLI:
+
+> **You:** `kroki pair kroki_eyJh...`  
+> **Agent:** Pairs with the specified profile and confirms readiness.  
+>  
+> **You:** `kroki найди на Avito Mac mini M4 и выпиши самые дешевые цены`  
+> **Agent:** Executes `kroki "<task>"`, waits for Kroki in the browser to finish, and summarizes the findings.
+
+### In Cursor / Claude Code
+
+Add the following to your agent prompt or rule file (`.cursorrules` or `CLAUDE.md`):
+
+```markdown
+When the user requests live browser interaction or running Kroki workflows:
+1. Ensure the profile is paired: run `npx kroki status`. If not paired, ask the user for their pairing code from https://kroki.one/devices.
+2. Pair via `npx kroki pair <CODE>`.
+3. Dispatch tasks via `npx kroki "<task>"` or workflows via `npx kroki run "<workflow>" '[vars]'`.
+```
+
+---
+
+## 🛠 Commands Reference
+
+| Command | Description |
+| :--- | :--- |
+| `npx kroki pair <code_from_devices>` | Connect to a specific browser profile (Chrome or Dolphin{anty}) |
+| `npx kroki "<browser_task>"` | Send an autonomous agent task to the active browser profile |
+| `npx kroki run "<workflow_name>" [json]` | Execute a saved Kroki deterministic workflow |
+| `npx kroki status` | View the currently paired profile and device info |
+| `npx kroki clear` | Clear active pairing session |
+| `npx kroki help` | Show usage options and help |
+
+---
+
+## 🔒 Security Architecture
+
+- **Zero Global Credentials**: Pairing codes are session-bound and scoped strictly to your selected browser window (`targetDeviceId`).
+- **Confirmation Gate**: The extension prompts you for confirmation on your computer when a connection attempt is made.
+- **Ultra Plan Scoped**: Cloud control channels require an active Ultra entitlement.
+- **Pure Native Node.js**: Zero third-party npm dependencies. Clean, audited, and lightweight.
+
+---
+
+## 📄 License
+
+MIT © [Kroki Team](https://kroki.one)

package/bin/kroki.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+
+/**
+ * Kroki CLI — Control Kroki browser automation from terminal & AI agents.
+ * Zero external dependencies. Uses native Node.js 18+ WebSocket & Fetch.
+ *
+ * https://kroki.one
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const CONFIG_DIR = join(homedir(), '.kroki');
+const SESSION_FILE = join(CONFIG_DIR, 'session.json');
+
+const DEFAULT_SUPABASE_URL = 'https://vjkzlvtvnmorokocnbhp.supabase.co';
+const DEFAULT_ANON_KEY =
+  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InZqa3psdnR2bm1vcm9rb2NuYmhwIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTY4NTI3NTcsImV4cCI6MjA3MjQyODc1N30.NZ4nMq2z8rFQZ2oMlYH0XJX3FrWI2T1j1vmF6vu1-HE';
+
+function ensureConfigDir() {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+function decodePairingCode(code) {
+  const trimmed = code.trim();
+  const raw = trimmed.startsWith('kroki_') ? trimmed.slice(6) : trimmed;
+  try {
+    const jsonStr = Buffer.from(raw, 'base64url').toString('utf8');
+    const parsed = JSON.parse(jsonStr);
+    if (!parsed.googleId || !parsed.token || !parsed.deviceId) {
+      throw new Error('Missing required fields in pairing code');
+    }
+    return parsed;
+  } catch {
+    throw new Error(
+      'Invalid Kroki pairing code.\nPlease copy a valid code from your Kroki Devices panel (https://kroki.one/devices).',
+    );
+  }
+}
+
+function getActiveSession() {
+  if (!existsSync(SESSION_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(SESSION_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveActiveSession(session) {
+  ensureConfigDir();
+  writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2), { mode: 0o600 });
+}
+
+function clearActiveSession() {
+  if (existsSync(SESSION_FILE)) {
+    unlinkSync(SESSION_FILE);
+  }
+}
+
+class RealtimeConnection {
+  constructor(config) {
+    this.url = config.supabaseUrl || DEFAULT_SUPABASE_URL;
+    this.anonKey = config.anonKey || DEFAULT_ANON_KEY;
+    this.token = config.token;
+    this.googleId = config.googleId;
+    this.deviceId = config.deviceId;
+    this.topic = `realtime:control:${this.googleId}`;
+    this.ref = 0;
+    this.ws = null;
+  }
+
+  nextRef() {
+    return String(++this.ref);
+  }
+
+  async connect(timeoutMs = 15000) {
+    return new Promise((resolve, reject) => {
+      const wsUrl = `${this.url.replace(/^http/, 'ws')}/realtime/v1/websocket?apikey=${this.anonKey}&vsn=1.0.0`;
+      this.ws = new globalThis.WebSocket(wsUrl);
+
+      const timer = setTimeout(() => {
+        if (this.ws) this.ws.close();
+        reject(new Error('Connection to Kroki Realtime timed out. Check your internet connection.'));
+      }, timeoutMs);
+
+      this.ws.onopen = () => {
+        clearTimeout(timer);
+        this.joinChannel()
+          .then(() => resolve(this))
+          .catch(reject);
+      };
+
+      this.ws.onerror = err => {
+        clearTimeout(timer);
+        reject(new Error(`WebSocket connection failed: ${err.message || 'network error'}`));
+      };
+    });
+  }
+
+  joinChannel() {
+    return new Promise((resolve, reject) => {
+      const joinRef = this.nextRef();
+      const payload = {
+        topic: this.topic,
+        event: 'phx_join',
+        payload: {
+          config: { broadcast: { self: false } },
+          access_token: this.token,
+        },
+        ref: joinRef,
+      };
+
+      const handler = event => {
+        try {
+          const msg = JSON.parse(event.data);
+          if (msg.ref === joinRef) {
+            this.ws.removeEventListener('message', handler);
+            if (msg.payload?.status === 'ok') {
+              resolve();
+            } else {
+              reject(new Error(`Channel join rejected: ${JSON.stringify(msg.payload || {})}`));
+            }
+          }
+        } catch {}
+      };
+
+      this.ws.addEventListener('message', handler);
+      this.ws.send(JSON.stringify(payload));
+    });
+  }
+
+  sendCommand(command, onEvent, timeoutMs = 240000) {
+    return new Promise((resolve, reject) => {
+      const msgRef = this.nextRef();
+      const timer = setTimeout(() => {
+        reject(new Error('Command timed out while waiting for browser response (4 min limit).'));
+      }, timeoutMs);
+
+      const handler = event => {
+        try {
+          const msg = JSON.parse(event.data);
+          if (msg.topic === this.topic && msg.event === 'broadcast') {
+            const envelope = msg.payload?.payload;
+            if (!envelope || envelope.deviceId !== this.deviceId) return;
+
+            if (onEvent) onEvent(envelope);
+
+            if (envelope.kind === 'chat_task_complete' || envelope.kind === 'workflow_complete') {
+              clearTimeout(timer);
+              this.ws.removeEventListener('message', handler);
+              resolve(envelope.payload);
+            } else if (envelope.kind === 'error') {
+              clearTimeout(timer);
+              this.ws.removeEventListener('message', handler);
+              reject(new Error(envelope.payload?.message || 'Remote error from Kroki browser'));
+            }
+          }
+        } catch {}
+      };
+
+      this.ws.addEventListener('message', handler);
+
+      const packet = {
+        topic: this.topic,
+        event: 'broadcast',
+        payload: {
+          type: 'broadcast',
+          event: 'command',
+          payload: command,
+        },
+        ref: msgRef,
+      };
+
+      this.ws.send(JSON.stringify(packet));
+    });
+  }
+
+  close() {
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {}
+      this.ws = null;
+    }
+  }
+}
+
+async function pairCommand(code) {
+  if (!code) {
+    console.error('Error: Pairing code required.\nUsage: npx kroki pair <kroki_code>\n');
+    console.error('Get your code from: https://kroki.one/devices');
+    process.exit(1);
+  }
+
+  const payload = decodePairingCode(code);
+  const name = payload.deviceName || payload.deviceId;
+  console.log(`\x1b[36mConnecting to profile [${name}]...\x1b[0m`);
+
+  const conn = new RealtimeConnection(payload);
+  await conn.connect();
+
+  saveActiveSession({
+    ...payload,
+    pairedAt: Date.now(),
+  });
+
+  conn.close();
+
+  console.log(`\x1b[32m✔ Successfully paired with "${name}".\x1b[0m`);
+  console.log('You can now run tasks without entering the code:');
+  console.log('  \x1b[33mnpx kroki "open example.com and extract titles"\x1b[0m');
+  console.log('  \x1b[33mnpx kroki run "My Workflow Name"\x1b[0m\n');
+}
+
+async function taskCommand(taskText) {
+  const session = getActiveSession();
+  if (!session) {
+    console.error('\x1b[31mError: Not paired.\x1b[0m');
+    console.error('First pair with your browser profile:\n  \x1b[33mnpx kroki pair <CODE_FROM_DEVICES>\x1b[0m\n');
+    console.error('Get your code from: https://kroki.one/devices');
+    process.exit(1);
+  }
+
+  const conn = new RealtimeConnection(session);
+  await conn.connect();
+
+  const command = {
+    v: 1,
+    id: `task-${Date.now()}`,
+    kind: 'chat_task',
+    targetDeviceId: session.deviceId,
+    taskId: `task-${Date.now()}`,
+    issuedAt: Date.now(),
+    payload: {
+      task: taskText,
+    },
+  };
+
+  try {
+    console.log(`\x1b[36m[Kroki: ${session.deviceName || 'Browser'}]\x1b[0m Running: "${taskText}"...`);
+    const result = await conn.sendCommand(command, ev => {
+      if (ev.kind === 'execution') {
+        const title = ev.payload?.title || ev.payload?.type;
+        if (title) console.log(`  \x1b[90m→ ${title}\x1b[0m`);
+      }
+    });
+
+    console.log('\x1b[32m✔ Task completed.\x1b[0m');
+    if (result && typeof result === 'object') {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } finally {
+    conn.close();
+  }
+}
+
+async function workflowCommand(nameOrId, varsJson) {
+  const session = getActiveSession();
+  if (!session) {
+    console.error('\x1b[31mError: Not paired.\x1b[0m');
+    console.error('Pair first with:\n  \x1b[33mnpx kroki pair <CODE>\x1b[0m\n');
+    process.exit(1);
+  }
+
+  let variables = {};
+  if (varsJson) {
+    try {
+      variables = JSON.parse(varsJson);
+    } catch {
+      console.error('Warning: Could not parse variables JSON, passing empty object.');
+    }
+  }
+
+  const conn = new RealtimeConnection(session);
+  await conn.connect();
+
+  const command = {
+    v: 1,
+    id: `wf-${Date.now()}`,
+    kind: 'workflow_execute',
+    targetDeviceId: session.deviceId,
+    taskId: `wf-${Date.now()}`,
+    issuedAt: Date.now(),
+    payload: {
+      workflowId: nameOrId,
+      variables,
+    },
+  };
+
+  try {
+    console.log(`\x1b[36m[Kroki: ${session.deviceName || 'Browser'}]\x1b[0m Executing workflow "${nameOrId}"...`);
+    const result = await conn.sendCommand(command, ev => {
+      if (ev.kind === 'workflow_step_start') {
+        console.log(`  \x1b[90m[step] ${ev.payload?.stepType || 'action'}: ${ev.payload?.comment || ''}\x1b[0m`);
+      }
+    });
+
+    console.log('\x1b[32m✔ Workflow finished.\x1b[0m');
+    if (result) console.log(JSON.stringify(result, null, 2));
+  } finally {
+    conn.close();
+  }
+}
+
+function statusCommand() {
+  const session = getActiveSession();
+  if (!session) {
+    console.log('\x1b[33mStatus: Not paired with any browser profile.\x1b[0m');
+    console.log('Pair with:\n  npx kroki pair <CODE_FROM_DEVICES>');
+  } else {
+    console.log('\x1b[32mStatus: Paired and Active\x1b[0m');
+    console.log(`Profile:   ${session.deviceName || session.deviceId}`);
+    console.log(`Device ID: ${session.deviceId}`);
+    console.log(`Platform:  ${session.platform || 'unknown'}`);
+    console.log(`Paired At: ${new Date(session.pairedAt).toLocaleString()}`);
+  }
+}
+
+function helpCommand() {
+  console.log(`
+\x1b[1mKroki CLI\x1b[0m — Control Kroki browser automation from terminal & AI agents
+
+\x1b[1mUsage:\x1b[0m
+  npx kroki pair <code_from_devices>       Pair with a browser profile (Chrome / Dolphin{anty})
+  npx kroki "<browser_task>"              Send an AI task to the paired browser
+  npx kroki run "<workflow_name>" [json]  Execute a deterministic workflow by name
+  npx kroki status                        Show currently paired profile
+  npx kroki clear                         Clear active pairing session
+  npx kroki help                          Show this help message
+
+\x1b[1mExamples:\x1b[0m
+  npx kroki pair kroki_eyJh...
+  npx kroki "find top 5 mechanical keyboards on Amazon and return prices"
+  npx kroki run "Export Leads" '{"limit": 50}'
+
+\x1b[1mDocs & Dashboard:\x1b[0m
+  https://kroki.one/devices
+`);
+}
+
+// ── Entry Point ─────────────────────────────────────────────────────────────
+
+const rawArgs = process.argv.slice(2);
+const first = rawArgs[0] || 'help';
+
+switch (first) {
+  case 'pair':
+  case 'connect':
+    pairCommand(rawArgs[1]).catch(e => {
+      console.error(`\x1b[31mError:\x1b[0m ${e.message}`);
+      process.exit(1);
+    });
+    break;
+
+  case 'run':
+  case 'workflow':
+    workflowCommand(rawArgs[1], rawArgs[2]).catch(e => {
+      console.error(`\x1b[31mError:\x1b[0m ${e.message}`);
+      process.exit(1);
+    });
+    break;
+
+  case 'status':
+    statusCommand();
+    break;
+
+  case 'clear':
+  case 'disconnect':
+    clearActiveSession();
+    console.log('\x1b[32m✔ Session cleared.\x1b[0m');
+    break;
+
+  case 'help':
+  case '--help':
+  case '-h':
+    helpCommand();
+    break;
+
+  default:
+    // If user ran `npx kroki "do something..."` directly
+    taskCommand(rawArgs.join(' ')).catch(e => {
+      console.error(`\x1b[31mError:\x1b[0m ${e.message}`);
+      process.exit(1);
+    });
+    break;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "kroki",
+  "version": "1.0.0",
+  "description": "Kroki Browser Automation CLI — Control Chrome & Dolphin{anty} from terminal and AI agents",
+  "keywords": [
+    "kroki",
+    "browser-automation",
+    "ai-agent",
+    "antigravity",
+    "dolphin-anty",
+    "chrome",
+    "mcp",
+    "cli"
+  ],
+  "author": "Kroki Team",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "kroki": "./bin/kroki.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/one-focus/kroki-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/one-focus/kroki-cli/issues"
+  },
+  "homepage": "https://kroki.one"
+}