ghostykit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Héctor BlisS (FixterGeek)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# Piloto UI · `ghostykit`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**An in-app copilot for React.** Piloto UI is the agent chat from
+[Ghosty Studio](https://www.ghosty.studio), packaged as a library. You drop it into an app you already
+have. It sees what the user has on screen, streams what the agent says and does, and **stops to ask
+before anything risky** (human in the loop).
+
+> El copiloto de tu app: el chat de Ghosty, probado en producción, como biblioteca. Español por default, inglés incluido.
+
+**[Open the playground →](https://blissito.github.io/ghostykit/)** (a fake backend, a real chat)
+
+![The permission pass: the agent asks before running a cron](https://raw.githubusercontent.com/blissito/ghostykit/main/docs/screenshots/ghosty-light-desktop-2-permission.png)
+
+## What you get
+
+- **Live answers**: markdown streamed at a readable pace (Streamdown), with code blocks and tables. External links ask for confirmation before opening.
+- **Agent steps**: every tool call as a line ("Read 2 files", "Searched the web"). Steps fold into a card when the turn ends, and you can show your own labels and icons.
+- **The permission pass**: risky actions arrive as a card with a countdown, *Approve* and *Reject*. A stamp lands when you answer, and the decision stays recorded under the reply.
+- **Context and references**: what the user is looking at travels with every turn. Rows from your app can be "@-mentioned" into the message.
+- **Resilience**: reconnects after a dropped network or a deploy, re-attaches to a running turn, retries while the server drains, and offers *Resume* when a turn is cut short.
+- **The composer**: attachments (you provide `upload`), voice notes (you provide `transcribe`), stop, model picker and reply-option buttons.
+- **Solid core**: the whole chat state is a pure reducer, `reducePilotEvent(state, name, data)`, tested by replaying real SSE sessions.
+
+## 30-second quickstart
+
+```bash
+npm i ghostykit motion streamdown
+```
+
+```tsx
+import { Piloto, useSseTransport } from "ghostykit";
+import "ghostykit/styles.css";
+import "ghostykit/fonts.css"; // optional: the house typefaces
+
+export function Copilot() {
+  const transport = useSseTransport("/api/copilot/conversations/123");
+  return <Piloto transport={transport} />;
+}
+```
+
+`<Piloto transport={…} />` works with nothing else. Give its container a height: Piloto fills it.
+
+## Transports
+
+A transport is how Piloto talks to your agent. It is a small interface: `subscribe`, `send`, `cancel`,
+plus optional `setModel`, `respondPermission` and `history`. Two are included.
+
+### 1. Split stream: `createSseTransport(base)` (Ghosty's contract)
+
+The event stream stays open (`EventSource`) and messages go by POST.
+
+| | |
+|---|---|
+| `GET  {base}/events` | Named SSE events: `started`, `status`, `chunk`, `thought`, `tool`, `permission`, `permission-resolved`, `usage`, `models`, `title`, `done{reposo?,interrumpido?,ultimo?}`, `error`… |
+| `POST {base}/messages` | `{content, images, primerTurno, retomar?, context?}` → `{inyectado?, estado?, turnId?}` |
+| `POST {base}/cancel` · `/model` · `/permission` | stop, switch model, answer a card |
+
+Messages sent during a running turn are injected into it (steer). A silent connection during a turn is
+reopened, and the server says whether the turn continued, finished or was cut short.
+
+### 2. POST returns the stream: `createPostStreamTransport({ url })` (EasyBits' contract)
+
+The POST that starts a turn *is* the SSE. A GET re-attaches to a running turn.
+
+| | |
+|---|---|
+| `POST {url}` | `{text, context?, turnId, continueTurnId?}` → SSE `started`, `chunk`, `tool{title,status}`, `permission{…, expiresAt}`, `done{turnId,text}`, `error`, `capacity`, `interrupted{turnId,canContinue}`, `idle` |
+| `GET {url}?attach=1` | `started`, one `permission` per open card, `snapshot{turnId,text,tools}`, then live |
+| `GET {url}` | `{messages:[{role,text}]}`, loaded as the thread |
+
+A 503 (deploy draining) is retried with the same `turnId`. A 409 `turn_busy` re-attaches to the turn
+that is already running. Approvals usually go through your own route:
+
+```tsx
+<Piloto
+  transport={useMemo(() => createPostStreamTransport({ url: "/api/v2/admin/copilot/chat" }), [])}
+  context={{ page: "crons", job: selectedJob }}
+  onPermission={async (id, optionId) => {
+    const res = await fetch(`/api/v2/admin/agent-actions/${id}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ decision: optionId === "approve" ? "approve" : "reject" }),
+    });
+    if (res.status === 409 || res.status === 404) return { resolved: false }; // expired or already answered
+    if (!res.ok) throw new Error("approval failed");
+    return { resolved: true, detail: (await res.json()).status };
+  }}
+/>
+```
+
+### 3. Your own
+
+Implement `PilotTransport` and emit the same event names (see `ghostykit/core` types). If you only need
+the state, use the reducer directly: `ghostykit/core` has no React dependency.
+
+## Make it yours
+
+```tsx
+const ref = useRef<PilotoHandle>(null);
+
+<Piloto
+  ref={ref}
+  transport={transport}
+  skin="easybits"            // "ghosty" (default) | "easybits" | "neutral" | your own
+  theme="auto"               // "light" | "dark" | "auto"
+  locale="en"                // Spanish by default
+  agentName="Admin assistant"
+  welcome="How can I help with your crons?"
+  suggestions={["Why did the monitor fail?"]}
+  context={() => ({ screen: "crons", selected })}            // sent with EVERY turn
+  toolVerbs={{ run_cron: { one: "Ran a cron", many: "Ran %n crons", running: "Running the cron…" } }}
+  upload={async (file) => ({ url: await myUpload(file) })}
+  transcribe={async (audio) => myWhisper(audio)}
+  onTurnDone={({ text }) => refreshMyData()}
+  slots={{ renderDeliveries: (turn) => <MyFiles turn={turn} />, composerExtras: <MyButton /> }}
+/>;
+
+ref.current?.addReference({ id: "12", label: "#12 Rosa" }); // "@" a row into the message
+ref.current?.send("Why did this fail?");                     // ask on the user's behalf
+```
+
+Other options: `strings`, `toolIcons`, `formatUserText`, `markdown`, `features`
+(`attachments`, `retry`, `copy`, `usage`, `models`, `replyOptions`, `duration`), `references` /
+`onReferencesChange`, `voiceNoteText`, `placeholder`, `avatar`, `initialTurns`, and the callbacks
+`onTurnStart`, `onTitle`, `onNeedsLogin`, `onDisconnected`, `onEvent`, `onSend`. To read the state
+outside the chat, call `usePilot(transport)` yourself and pass the result as `pilot`. Every piece is
+exported (`AgentBubble`, `AgentSteps`, `Composer`, `ConfirmCard`, `Markdown`, …) if you want to build
+your own layout.
+
+### Skins and theming
+
+`ghostykit/styles.css` is self-contained and scoped under `.piloto`. It works the same with
+**Tailwind 3, Tailwind 4 or no Tailwind** (verified in a Tailwind 3 app: its utilities compute
+identically with and without Piloto's CSS). Every color, radius, border width and shadow is a
+variable:
+
+```css
+.my-app .piloto {
+  --piloto-accent: #0f766e;
+  --piloto-warning: #fde68a;      /* the permission pass */
+  --piloto-radius-card: 6px;
+  --piloto-border-width: 3px;
+  --piloto-shadow-hero: 6px 6px 0 #0f766e;
+  --piloto-font: "Your Sans", sans-serif;
+}
+```
+
+| Ghosty | EasyBits | Neutral |
+|---|---|---|
+| ![Ghosty skin](https://raw.githubusercontent.com/blissito/ghostykit/main/docs/screenshots/ghosty-light-mobile-2-permission.png) | ![EasyBits skin, dark](https://raw.githubusercontent.com/blissito/ghostykit/main/docs/screenshots/easybits-dark-mobile-2-permission.png) | ![Neutral skin](https://raw.githubusercontent.com/blissito/ghostykit/main/docs/screenshots/neutral-light-mobile-2-permission.png) |
+
+## Accessibility
+
+- Keyboard-first: Enter sends, Shift+Enter adds a new line, Backspace on an empty box removes the last reference. Menus close with Escape, and focus rings are visible (`--piloto-focus`).
+- The permission pass is a labelled region; the stamp is announced as status, and errors as alerts.
+- `prefers-reduced-motion` turns off every animation, including the text-at-pace effect, the stamp and the "thinking" lamps.
+- Dark mode is real, not inverted: hard shadows switch to a color so they stay visible on dark backgrounds.
+
+## The repo
+
+- `packages/ghostykit`: the package (`core`, `transport`, `react`, `pointer`, `styles.css`, `fonts.css`)
+- `apps/demo`: the playground (Vite, simulated transport, skin switcher)
+
+```bash
+npm install
+npm test        # reducer, both transports, parsers, SSR
+npm run build   # dist/ (JS + .d.ts + styles.css)
+npm run demo    # http://localhost:5173
+```
+
+## License
+
+MIT © Héctor BlisS (FixterGeek)

package/dist/chunks/chunk-6U545WJG.js

@@ -0,0 +1,36 @@
+// src/core/text.ts
+var VOICE_NOTE = /\[Nota de voz transcrita[^\]]*\]\s*«([^»]*)»/;
+function cleanUserText(raw) {
+  let t = raw;
+  const voice = t.match(VOICE_NOTE);
+  if (voice) t = t.replace(voice[0], voice[1]);
+  return t.replace(/\n{3,}/g, "\n\n").trim();
+}
+function systemNoteOf(text) {
+  if (!text.startsWith("\u23F0 ")) return null;
+  const cause = text.match(/^⏰ [^(\n]*\(([^)]+)\)/)?.[1] ?? text.split("\n")[0].replace(/^⏰ /, "").replace(/[.:].*$/, "").slice(0, 60);
+  return cause.toLowerCase();
+}
+function applyReferences(text, refs) {
+  if (!refs.length) return text;
+  const lines = refs.filter((r) => r.prompt).map((r) => r.prompt);
+  const labels = refs.filter((r) => !r.prompt).map((r) => r.label);
+  let out = text;
+  if (labels.length) out = `[${labels.join(", ")}] ${out}`.trim();
+  if (lines.length) out = `${lines.join("\n")}
+${out}`;
+  return out;
+}
+function formatDuration(s) {
+  if (s < 60) return `${s} s`;
+  const min = Math.floor(s / 60);
+  if (min < 60) return `${min} min`;
+  return `${Math.floor(min / 60)} h ${String(min % 60).padStart(2, "0")} min`;
+}
+
+export {
+  cleanUserText,
+  systemNoteOf,
+  applyReferences,
+  formatDuration
+};

package/dist/chunks/chunk-KZOMMG2D.js

@@ -0,0 +1,365 @@
+// src/transport/types.ts
+var PilotHttpError = class extends Error {
+  constructor(message, status, needsLogin = false) {
+    super(message);
+    this.name = "PilotHttpError";
+    this.status = status;
+    this.needsLogin = needsLogin;
+  }
+};
+
+// src/transport/postStream.ts
+async function readSse(body, onMessage, onBytes) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let event = "message";
+  let data = [];
+  const flush = () => {
+    if (data.length) onMessage({ event, data: data.join("\n") });
+    event = "message";
+    data = [];
+  };
+  for (; ; ) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    onBytes?.();
+    buffer += decoder.decode(value, { stream: true });
+    let nl;
+    while ((nl = buffer.search(/\r\n|\r|\n/)) >= 0) {
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + (buffer[nl] === "\r" && buffer[nl + 1] === "\n" ? 2 : 1));
+      if (line === "") flush();
+      else if (line.startsWith(":")) continue;
+      else {
+        const i = line.indexOf(":");
+        const field = i < 0 ? line : line.slice(0, i);
+        const val = i < 0 ? "" : line.slice(i + 1).replace(/^ /, "");
+        if (field === "event") event = val;
+        else if (field === "data") data.push(val);
+      }
+    }
+  }
+  flush();
+}
+var TERMINAL = /* @__PURE__ */ new Set(["done", "capacity", "interrupted", "idle"]);
+function parse(raw) {
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function defaultHistory(json) {
+  const msgs = json?.messages ?? [];
+  return msgs.filter((m) => typeof m.text === "string").map((m) => ({ role: m.role === "user" ? "user" : "assistant", text: m.text }));
+}
+function uuid() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `t-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function createPostStreamTransport(target, options = {}) {
+  const url = typeof target === "string" ? target : target.url;
+  const opts = typeof target === "string" ? options : { ...target, ...options };
+  const doFetch = (...a) => (opts.fetch ?? fetch)(...a);
+  const credentials = opts.credentials ?? "same-origin";
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const retries = opts.retries ?? 6;
+  const silenceMs = opts.silenceMs ?? 6e4;
+  const attachUrl = opts.attachUrl === void 0 ? `${url}${url.includes("?") ? "&" : "?"}attach=1` : opts.attachUrl;
+  const historyUrl = opts.historyUrl === void 0 ? url : opts.historyUrl;
+  const buildBody = opts.body ?? ((i) => ({
+    text: i.text,
+    ...i.context !== void 0 ? { context: i.context } : {},
+    turnId: i.turnId,
+    ...i.resume && i.resumeTurnId ? { continueTurnId: i.resumeTurnId } : {}
+  }));
+  let listener = null;
+  let isBusy = () => false;
+  let closed = false;
+  let current = null;
+  const emit = (name, data) => listener?.(name, data);
+  async function consume(res, ctrl) {
+    if (!res.body) return false;
+    let terminal = false;
+    let errored = false;
+    let lastByte = Date.now();
+    const watchdog = setInterval(() => {
+      if (Date.now() - lastByte > silenceMs) ctrl.abort();
+    }, Math.min(15e3, silenceMs));
+    try {
+      await readSse(
+        res.body,
+        ({ event, data }) => {
+          if (ctrl.signal.aborted) return;
+          const d = parse(data);
+          emit(event, d);
+          if (event === "error") errored = true;
+          if (TERMINAL.has(event)) terminal = true;
+        },
+        () => {
+          lastByte = Date.now();
+        }
+      );
+    } catch {
+    } finally {
+      clearInterval(watchdog);
+    }
+    if (errored && !terminal) {
+      emit("done", {});
+      return true;
+    }
+    return terminal;
+  }
+  async function attach() {
+    if (!attachUrl) return;
+    for (let attempt = 0; attempt <= retries && !closed; attempt++) {
+      const ctrl = new AbortController();
+      current?.abort();
+      current = ctrl;
+      try {
+        const res = await doFetch(attachUrl, { credentials, headers: { accept: "text/event-stream" }, signal: ctrl.signal });
+        if (res.ok && await consume(res, ctrl)) return;
+        if (ctrl.signal.aborted && current !== ctrl) return;
+      } catch {
+        if (current !== ctrl) return;
+      }
+      if (!isBusy()) return;
+      await sleep(Math.min(1e3 * 2 ** attempt, 1e4));
+    }
+  }
+  return {
+    // Sin steer: con un turno corriendo el servidor contesta 409. El composer no deja mandar.
+    steer: false,
+    subscribe(l, sub = {}) {
+      listener = l;
+      isBusy = sub.isBusy ?? (() => false);
+      closed = false;
+      void attach();
+      return () => {
+        closed = true;
+        listener = null;
+        current?.abort();
+        current = null;
+      };
+    },
+    async history() {
+      if (!historyUrl) return [];
+      const res = await doFetch(historyUrl, { credentials, headers: { accept: "application/json" } });
+      if (!res.ok) return [];
+      return (opts.parseHistory ?? defaultHistory)(await res.json().catch(() => null));
+    },
+    async send(input) {
+      const turnId = (opts.newTurnId ?? uuid)();
+      const body = JSON.stringify(buildBody({ ...input, turnId }));
+      for (let attempt = 0; ; attempt++) {
+        const ctrl = new AbortController();
+        current?.abort();
+        current = ctrl;
+        const res = await doFetch(url, {
+          method: "POST",
+          credentials,
+          headers: { "content-type": "application/json", accept: "text/event-stream" },
+          body,
+          signal: ctrl.signal
+        });
+        if (res.status === 503 && attempt < retries) {
+          await sleep(Number(res.headers.get("Retry-After")) * 1e3 || 3e3);
+          continue;
+        }
+        if (!res.ok) {
+          const json = await res.json().catch(() => null);
+          const err = new PilotHttpError(json?.message ?? json?.error ?? `Error ${res.status}`, res.status, res.headers.get("X-Needs-Login") != null);
+          if (json?.error) err.code = json.error;
+          if (res.status === 409 && json?.error === "turn_busy") void attach();
+          throw err;
+        }
+        void consume(res, ctrl).then((ok) => {
+          if (!ok && current === ctrl && !closed) void attach();
+        });
+        return { turnId, state: "running" };
+      }
+    },
+    async cancel() {
+      if (opts.cancelUrl) await doFetch(opts.cancelUrl, { method: "POST", credentials }).catch(() => {
+      });
+      current?.abort();
+      current = null;
+    }
+  };
+}
+
+// src/transport/index.ts
+var SSE_EVENTS = [
+  "started",
+  "status",
+  "caps",
+  "models",
+  "chunk",
+  "thought",
+  "tool",
+  "artifact",
+  "usage",
+  "title",
+  "done",
+  "error",
+  "warning",
+  "reemplazo",
+  "permission",
+  "permission-resolved",
+  "closed",
+  "page-plan",
+  "section-building",
+  "section-update",
+  "section",
+  "page-ready",
+  "page-error",
+  "page-planning",
+  "page-drop",
+  "review",
+  "page-version",
+  "page-edit",
+  // Los de un servidor de turnos durables (EasyBits): re-enganche, sin turno, cortado, sin lugar.
+  "snapshot",
+  "idle",
+  "interrupted",
+  "capacity"
+];
+var LIFE_EVENTS = /* @__PURE__ */ new Set([
+  "started",
+  "status",
+  "chunk",
+  "thought",
+  "tool",
+  "artifact",
+  "usage",
+  "done",
+  "error",
+  "warning",
+  "reemplazo",
+  "permission",
+  "page-plan",
+  "section-building",
+  "section-update",
+  "section",
+  "page-ready",
+  "page-error",
+  "page-planning",
+  "page-drop",
+  "review",
+  "page-version",
+  "page-edit",
+  "snapshot",
+  "idle",
+  "interrupted",
+  "capacity"
+]);
+var SILENCE_MAX_MS = 11 * 6e4;
+var MISSED_BEATS = 4;
+var MIN_SILENCE_MS = 9e4;
+function parse2(raw) {
+  if (typeof raw !== "string" || !raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function createSseTransport(base, opts = {}) {
+  const doFetch = (...args) => (opts.fetch ?? fetch)(...args);
+  const now = opts.now ?? Date.now;
+  const root = base.replace(/\/+$/, "");
+  let lastEventAt = now();
+  const post = (path, body) => doFetch(`${root}/${path}`, {
+    method: "POST",
+    headers: body === void 0 ? void 0 : { "content-type": "application/json" },
+    body: body === void 0 ? void 0 : JSON.stringify(body),
+    credentials: opts.withCredentials ? "include" : void 0
+  });
+  return {
+    subscribe(listener, sub = {}) {
+      const ES = opts.EventSource ?? globalThis.EventSource;
+      if (!ES) throw new Error("ghostykit: no hay EventSource en este entorno (pasa `EventSource` en las opciones)");
+      let es = null;
+      let heartbeatMs = null;
+      let closed = false;
+      const open = () => {
+        const source = new ES(`${root}/events`, { withCredentials: Boolean(opts.withCredentials) });
+        es = source;
+        const names = /* @__PURE__ */ new Set([...SSE_EVENTS, ...opts.events ?? []]);
+        for (const name of names) {
+          source.addEventListener(name, (e) => {
+            if (es !== source) return;
+            if (LIFE_EVENTS.has(name)) lastEventAt = now();
+            const raw = e.data;
+            if (name === "error" && (raw === void 0 || raw === "")) return;
+            const data = parse2(raw);
+            if (name === "started") {
+              const d = data;
+              heartbeatMs = typeof d?.latidoMs === "number" && d.latidoMs > 0 ? d.latidoMs : null;
+            }
+            listener(name, data);
+            if (name === "closed") source.close();
+          });
+        }
+      };
+      open();
+      const timer = setInterval(() => {
+        if (closed || !sub.isBusy?.()) return;
+        const cap = heartbeatMs ? Math.max(heartbeatMs * MISSED_BEATS, MIN_SILENCE_MS) : SILENCE_MAX_MS;
+        if (now() - lastEventAt < cap) return;
+        lastEventAt = now();
+        es?.close();
+        open();
+      }, opts.checkEveryMs ?? 15e3);
+      return () => {
+        closed = true;
+        clearInterval(timer);
+        es?.close();
+        es = null;
+      };
+    },
+    async send(input) {
+      lastEventAt = now();
+      const res = await post("messages", {
+        content: input.text,
+        images: input.attachments,
+        // Lo que hace que el hilo se BAUTICE al cerrar este turno.
+        primerTurno: input.firstTurn,
+        ...input.resume ? { retomar: true } : {},
+        ...input.context !== void 0 ? { context: input.context } : {}
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new PilotHttpError(text || `Error ${res.status}`, res.status, Boolean(res.headers.get("X-Needs-Login")));
+      }
+      const r = await res.json().catch(() => ({}));
+      return { injected: r.inyectado, state: r.estado, turnId: r.turnId };
+    },
+    async cancel() {
+      await post("cancel").catch(() => {
+      });
+    },
+    async setModel(value) {
+      await post("model", { value });
+    },
+    async respondPermission(id, optionId) {
+      const res = await post("permission", { id, optionId });
+      const r = await res.json().catch(() => ({}));
+      return { resolved: Boolean(r.resuelto ?? r.resolved) };
+    }
+  };
+}
+
+export {
+  PilotHttpError,
+  readSse,
+  createPostStreamTransport,
+  SSE_EVENTS,
+  SILENCE_MAX_MS,
+  MISSED_BEATS,
+  MIN_SILENCE_MS,
+  createSseTransport
+};