ghosty-acp 0.0.1

package/README.md

@@ -0,0 +1,146 @@
+# ghosty-acp
+
+Connect your editor to an [ACP](https://agentclientprotocol.com) agent running on another
+machine.
+
+Editors launch a **command** and talk to it over standard input/output. A remote agent
+lives behind a **WebSocket**. This swaps the cable — nothing else. No translation, no
+state, no dependencies.
+
+Not tied to any agent or vendor: if the other end speaks ACP over WebSocket, this works.
+
+## Install
+
+Nothing to install — `npx` fetches it:
+
+```
+npx -y ghosty-acp wss://your-agent.example.com/acp
+```
+
+## Zed
+
+`settings.json`:
+
+```jsonc
+{
+  "agent_servers": {
+    "My agent": {
+      "type": "custom",
+      "command": "npx",
+      "args": ["-y", "ghosty-acp", "wss://your-agent.example.com/acp"],
+      "env": { "GHOSTY_ACP_TOKEN": "…" }
+    }
+  }
+}
+```
+
+## VS Code
+
+Install the **ACP Client** extension, then in `settings.json`:
+
+```jsonc
+{
+  "acp.agents": {
+    "My agent": {
+      "command": "npx",
+      "args": ["-y", "ghosty-acp", "wss://your-agent.example.com/acp"],
+      "env": { "GHOSTY_ACP_TOKEN": "…" }
+    }
+  }
+}
+```
+
+The token is optional — omit it if the other end doesn't require one.
+
+## ⚠️ Put the token in `env`, never in `args`
+
+Any process on your machine can read another process's arguments with `ps`. The token is
+read from `GHOSTY_ACP_TOKEN` and appended to the URL inside the process.
+
+## Troubleshooting
+
+Diagnostics go to **stderr**; stdout carries only the JSON-RPC stream, because anything
+else there breaks the editor.
+
+| Message | Meaning |
+|---|---|
+| `rechazado (1006)` | Bad credential, or the server refused the connection |
+| `la máquina estaba en reposo…` | The agent was asleep; connecting wakes it |
+| `conexión cerrada (…)` | The other end closed; the bridge exits so the editor notices |
+
+Requires Node 22+. MIT.
+
+---
+
+# ghosty-acp — en español
+
+Conecta tu editor a un agente [ACP](https://agentclientprotocol.com) que corre en otra
+máquina.
+
+Los editores lanzan un **comando** y le hablan por entrada y salida estándar. Un agente
+remoto vive detrás de un **WebSocket**. Esto cambia el cable, y nada más: no traduce, no
+guarda nada, no tiene dependencias.
+
+No es de ningún agente ni de ningún proveedor en particular: si el otro extremo habla ACP
+sobre WebSocket, sirve.
+
+## Instalación
+
+Nada que instalar — `npx` lo descarga:
+
+```
+npx -y ghosty-acp wss://tu-agente.example.com/acp
+```
+
+## Zed
+
+En `settings.json`:
+
+```jsonc
+{
+  "agent_servers": {
+    "Mi agente": {
+      "type": "custom",
+      "command": "npx",
+      "args": ["-y", "ghosty-acp", "wss://tu-agente.example.com/acp"],
+      "env": { "GHOSTY_ACP_TOKEN": "…" }
+    }
+  }
+}
+```
+
+## VS Code
+
+Instala la extensión **ACP Client** y en `settings.json`:
+
+```jsonc
+{
+  "acp.agents": {
+    "Mi agente": {
+      "command": "npx",
+      "args": ["-y", "ghosty-acp", "wss://tu-agente.example.com/acp"],
+      "env": { "GHOSTY_ACP_TOKEN": "…" }
+    }
+  }
+}
+```
+
+El token es opcional: si el otro extremo no pide credencial, omítelo.
+
+## ⚠️ El token va en `env`, nunca en `args`
+
+Los argumentos de un proceso los puede leer cualquier otro proceso de la máquina con un
+`ps`. Por eso se lee de `GHOSTY_ACP_TOKEN` y se añade a la URL ya dentro del proceso.
+
+## Cuando algo falla
+
+Todo lo que el puente cuenta va a la **salida de error**; la salida estándar es sólo el
+flujo JSON-RPC, porque cualquier otra cosa ahí rompe al editor.
+
+| Mensaje | Qué pasa |
+|---|---|
+| `rechazado (1006)` | La credencial no vale, o el servidor no aceptó la conexión |
+| `la máquina estaba en reposo…` | El agente estaba dormido; la conexión lo despierta |
+| `conexión cerrada (…)` | El otro extremo cerró; el puente sale para que el editor se entere |
+
+Necesita Node 22 o superior. MIT.

package/bridge.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Puente ACP: el editor de un lado, la caja del agente del otro.
+//
+//   node bridge.mjs wss://acp-<agentId>.sandboxes.easybits.cloud/acp
+//   GHOSTY_ACP_TOKEN=gat_… node bridge.mjs <url>
+//
+// POR QUÉ EXISTE. Un agente de ghosty.studio vive en una microVM y se habla por
+// WebSocket. Los editores —Zed, JetBrains, los plugins de neovim— no consumen una URL:
+// ejecutan un COMANDO y le escriben JSON-RPC por stdin. Sin esta pieza, la dirección
+// `wss://` que reparte el panel no la puede usar ningún editor, por muy correcta que sea.
+//
+// No traduce nada: mueve líneas. ACP es JSON-RPC delimitado por saltos de línea, así que
+// lo único que hay aquí es el cambio de cable.
+//
+// Node puro y CERO dependencias: Node 22 trae `WebSocket` global. Un puente que exija
+// `npm install` deja de ser una línea en el settings.json de alguien.
+
+const url = process.argv[2];
+const token = process.env.GHOSTY_ACP_TOKEN || "";
+
+if (!url) {
+  console.error("uso: node bridge.mjs <wss://…/acp>   (token en GHOSTY_ACP_TOKEN)");
+  process.exit(2);
+}
+
+// ⚠️ El token va por ENV y nunca por argv: la línea de comandos de un proceso la lee
+// cualquiera con un `ps` en esa máquina, y esto es una credencial de acceso al agente.
+const target = new URL(url);
+if (token) target.searchParams.set("token", token);
+
+// stdout es SÓLO el flujo JSON-RPC. Todo diagnóstico va a stderr o el editor se
+// atraganta con lo que no esperaba — el mismo criterio con el que el relé no le manda al
+// cliente el stderr del agente.
+const diag = (m) => process.stderr.write(`[ghosty-acp] ${m}\n`);
+
+diag(`conectando a ${target.origin}${target.pathname}…`);
+// La caja hiberna a los 15 minutos de ocio; la primera conexión la despierta y eso tarda
+// unos segundos. Se avisa para que el silencio no se lea como un cuelgue.
+const avisoLento = setTimeout(() => diag("la máquina estaba en reposo, despertándola…"), 3000);
+
+const ws = new WebSocket(target);
+
+// ⚠️ COLA DE SALIDA, y no es un lujo. El editor escribe `initialize` en cuanto lanza el
+// proceso —antes de que el WebSocket haya abierto, y más aún si la caja estaba dormida y
+// tarda segundos—. Descartar esas líneas deja al editor esperando una respuesta que nadie
+// llegó a oír: se ve como un agente que no arranca, sin un solo error. Se guardan y se
+// sueltan en orden al abrir.
+let cola = [];
+
+ws.onopen = () => {
+  clearTimeout(avisoLento);
+  diag("listo");
+  for (const linea of cola) ws.send(linea + "\n");
+  cola = [];
+};
+
+ws.onerror = (e) => {
+  clearTimeout(avisoLento);
+  // El evento de error de esta API trae poco; el `onclose` que viene detrás trae el
+  // código, y ahí está el diagnóstico bueno. Se imprime lo que haya por si acaso.
+  diag(`error de conexión${e?.message ? `: ${e.message}` : ""}`);
+};
+
+ws.onclose = (e) => {
+  clearTimeout(avisoLento);
+  // 1006 sin motivo es lo que se ve cuando el servidor rechaza el upgrade: casi siempre
+  // el token. Decirlo aquí evita el rato de mirar el editor pensando que es cosa suya.
+  if (e.code === 1006 && !e.reason) {
+    diag(token ? "rechazado (1006): revisa el token de este agente" : "rechazado (1006): falta GHOSTY_ACP_TOKEN");
+  } else {
+    diag(`conexión cerrada (${e.code}${e.reason ? `: ${e.reason}` : ""})`);
+  }
+  // Salir es parte del contrato con el editor: un proceso que sigue vivo con el cable
+  // muerto se ve como un agente que dejó de contestar, sin decir nunca que murió.
+  process.exit(e.code === 1000 ? 0 : 1);
+};
+
+// ── caja → editor ────────────────────────────────────────────────────────────────
+//
+// ⚠️ EL SALTO DE LÍNEA NO ES DECORACIÓN. El relé manda cada mensaje SIN `\n` final,
+// porque en un WebSocket el frame YA es la frontera. Pero el editor lee un FLUJO de
+// bytes y espera el delimitador: si se vuelca el frame tal cual, se queda con el mensaje
+// entero en su buffer esperando un salto que no llega, y **cuelga sin un solo error**.
+// Es el primer bug que tuvo este transporte y no se ve en ninguna traza.
+//
+// Se parte por si vinieran varios mensajes en un frame; no se guarda nada entre frames.
+ws.onmessage = (e) => {
+  for (const linea of String(e.data).split("\n")) {
+    const t = linea.trim();
+    if (t) process.stdout.write(t + "\n");
+  }
+};
+
+// ── editor → caja ────────────────────────────────────────────────────────────────
+//
+// Aquí SÍ hace falta acumular: stdin es un flujo y un mensaje puede llegar partido en
+// dos chunks. Se emite sólo lo que ya tiene su salto de línea.
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let nl;
+  while ((nl = buffer.indexOf("\n")) !== -1) {
+    const linea = buffer.slice(0, nl).trim();
+    buffer = buffer.slice(nl + 1);
+    if (!linea) continue;
+    // Si el socket aún no está abierto la línea se descarta y se dice: mandarla al vacío
+    // en silencio dejaría al editor esperando para siempre una respuesta que nadie oyó.
+    if (ws.readyState === WebSocket.CONNECTING) {
+      cola.push(linea);
+      continue;
+    }
+    if (ws.readyState !== WebSocket.OPEN) {
+      diag("mensaje descartado: la conexión está cerrada");
+      continue;
+    }
+    ws.send(linea + "\n");
+  }
+});
+
+// El editor cierra stdin cuando termina con el agente. Cerrar limpio (1000) para que la
+// caja libere su sesión en vez de esperar a que expire el socket.
+// ⚠️ Con la cola aún pendiente, cerrar aquí tiraría lo que no ha salido. Sólo se cierra
+// si ya no hay nada esperando; si lo hay, lo hará el `onclose` de la caja o el propio
+// editor al matar el proceso.
+process.stdin.on("end", () => {
+  if (ws.readyState === WebSocket.OPEN && cola.length === 0) ws.close(1000, "stdin cerrado");
+});

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "ghosty-acp",
+  "version": "0.0.1",
+  "description": "Conecta tu editor a un agente ACP remoto. Puente entre entrada/salida estándar y WebSocket, sin dependencias.",
+  "type": "module",
+  "bin": { "ghosty-acp": "bridge.mjs" },
+  "files": ["bridge.mjs", "README.md"],
+  "engines": { "node": ">=22" },
+  "keywords": ["acp", "agent-client-protocol", "zed", "vscode", "neovim", "agent"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/blissito/ghosty-studio.git", "directory": "packages/acp-bridge" },
+  "homepage": "https://www.ghosty.studio/docs/acp"
+}