@crievo/omni 0.0.0-stage → 0.1.0

package/tools/lib/channel.mjs

@@ -0,0 +1,399 @@
+/* The runner channel's protocol: HTTP requests and their streaming bodies over one WebSocket, between the
+   cloud's RunnerHub (a Durable Object) and the Mac's studio (`studio.ts --runner`). The same code runs on
+   both sides: Bun, Node (tests) and the Workers runtime.
+
+   Every message is one binary frame: a 4-byte big-endian header length, the JSON header, then the
+   payload (body bytes, only on `data`). Requests carry an id; a request body is the stream `q<id>` and
+   the response body `s<id>`.
+
+     req   {id, method, path, headers, body}   ask the other side (`onRequest`) to answer
+     res   {id, status, headers, body}         the answer's head; the body follows as a stream
+     err   {id, message}                       the request failed before an answer
+     abort {id}                                the asker gave up (timeout): stop handling it
+     data  {s} + bytes                         one chunk, at most CHUNK bytes, spends one credit
+     end   {s}                                 the stream is over
+     fail  {s, message}                        the sender's stream broke
+     more  {s, n}                              the receiver grants n more chunks
+     cancel {s}                                the receiver no longer wants the stream
+
+   Flow control: a sender only sends what was granted, and the receiver grants up to WINDOW chunks as its
+   reader pulls, so one stream never holds more than about WINDOW × CHUNK in memory on either side.
+
+   Two things keep a live stream (Omni's turn: many small NDJSON lines) quick on a slow uplink:
+   - while it waits for credit, what the source gives piles up and goes as one frame, so a credit
+     carries many lines instead of one;
+   - a bulk stream (a video, an image) sends smaller frames, and only while the socket's own queue
+     (`backlog`) is short: a live line never waits behind megabytes of media. */
+
+export const CHUNK = 512 * 1024;
+/* a bulk stream's frame, and how much the socket may hold before its next one waits */
+export const BULK_CHUNK = 128 * 1024;
+export const BULK_BACKLOG = 256 * 1024;
+const BULK_POLL_MS = 10;
+/* how many pieces the read-ahead holds at most (a source of tiny writes stops there too) */
+const MAX_PIECES = 256;
+/* a body of these types is live (events, JSON); everything else is bulk */
+const LIVE = /ndjson|event-stream|json|^text\//i;
+/* the close code the hub sends an older runner when a newer one connects: that one stops, not retries */
+export const REPLACED = 4000;
+/* the close code for a runner whose key was deleted ("Desconectar"): it stops until paired again */
+export const REVOKED = 4003;
+/* the close code for a runner the hub can't talk to (different PROTOCOL): it says which side to update */
+export const UPGRADE = 4004;
+/* bumped when the frames or the headers between the runner and the hub change in a way the other side can't
+   read; the runner sends it on connect (x-ov-protocol), and a missing header counts as 1 */
+export const PROTOCOL = 1;
+export const WINDOW = 4;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const NO_BODY = new Set([101, 204, 205, 304]);
+
+export class ChannelError extends Error {
+  /** @param {string} message @param {"timeout" | "closed" | "remote"} code */
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** @param {object} head @param {Uint8Array} [payload] */
+export function encodeFrame(head, payload) {
+  const h = encoder.encode(JSON.stringify(head));
+  const out = new Uint8Array(4 + h.byteLength + (payload?.byteLength ?? 0));
+  new DataView(out.buffer).setUint32(0, h.byteLength);
+  out.set(h, 4);
+  if (payload) out.set(payload, 4 + h.byteLength);
+  return out;
+}
+
+/** @param {ArrayBuffer | Uint8Array} data @returns {{ head: any, payload: Uint8Array }} */
+export function decodeFrame(data) {
+  const b = data instanceof Uint8Array ? data : new Uint8Array(data);
+  const n = new DataView(b.buffer, b.byteOffset, b.byteLength).getUint32(0);
+  return { head: JSON.parse(decoder.decode(b.subarray(4, 4 + n))), payload: b.subarray(4 + n) };
+}
+
+const message = (/** @type {unknown} */ e) => String(/** @type {Error} */ (e)?.message ?? e);
+
+/**
+ * One side of the channel.
+ * @typedef {{
+ *   send: (frame: Uint8Array) => void,
+ *   onRequest?: ((request: Request) => Response | Promise<Response>) | null,
+ *   wrapBody?: ((body: ReadableStream, headers: Headers) => ReadableStream) | null,
+ *   backlog?: () => number,
+ * }} PeerOptions
+ */
+export class Peer {
+  /** @param {PeerOptions} o */
+  constructor({ send, onRequest = null, wrapBody = null, backlog = () => 0 }) {
+    this.send = send;
+    this.onRequest = onRequest;
+    this.wrapBody = wrapBody;
+    /* bytes the socket still holds to send (WebSocket.bufferedAmount); 0 where it can't be read */
+    this.backlog = backlog;
+    this.nextId = 1;
+    this.closed = false;
+    /** @type {Map<number, { resolve: (r: Response) => void, reject: (e: Error) => void, timer: any }>} */
+    this.waiting = new Map();
+    /** @type {Map<string, { push: (p: Uint8Array) => void, end: () => void, fail: (m: string) => void }>} */
+    this.inbound = new Map();
+    /** @type {Map<string, { grant: (n: number) => void, cancel: () => void }>} */
+    this.outbound = new Map();
+    /** @type {Map<number, AbortController>} */
+    this.handling = new Map();
+  }
+
+  /** @param {object} head @param {Uint8Array} [payload] */
+  frame(head, payload) {
+    if (!this.closed) this.send(encodeFrame(head, payload));
+  }
+
+  /** Asks the other side; resolves with its Response once the head arrives (the body streams after).
+   *  @param {Request} request @param {{ timeoutMs?: number }} [o] @returns {Promise<Response>} */
+  request(request, { timeoutMs = 30_000 } = {}) {
+    if (this.closed) return Promise.reject(new ChannelError("o canal está fechado", "closed"));
+    const id = this.nextId++;
+    const url = new URL(request.url);
+    const body = !!request.body && request.method !== "GET" && request.method !== "HEAD";
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.waiting.delete(id);
+        this.outbound.get(`q${id}`)?.cancel();
+        this.frame({ t: "abort", id });
+        reject(new ChannelError("o Mac não respondeu a tempo", "timeout"));
+      }, timeoutMs);
+      this.waiting.set(id, { resolve, reject, timer });
+      this.frame({
+        t: "req",
+        id,
+        method: request.method,
+        path: url.pathname + url.search,
+        headers: [...request.headers],
+        body,
+      });
+      if (body && request.body)
+        this.pump(`q${id}`, request.body, undefined, !LIVE.test(request.headers.get("content-type") ?? ""));
+    });
+  }
+
+  /** One frame from the socket. @param {ArrayBuffer | Uint8Array} data */
+  receive(data) {
+    const { head: h, payload } = decodeFrame(data);
+    switch (h.t) {
+      case "req":
+        return void this.handle(h);
+      case "res": {
+        const w = this.waiting.get(h.id);
+        if (!w) {
+          if (h.body) this.frame({ t: "cancel", s: `s${h.id}` });
+          return;
+        }
+        clearTimeout(w.timer);
+        this.waiting.delete(h.id);
+        const headers = new Headers(h.headers);
+        let body = h.body ? this.incoming(`s${h.id}`) : null;
+        if (body && this.wrapBody) body = this.wrapBody(body, headers);
+        return w.resolve(new Response(body, { status: h.status, headers }));
+      }
+      case "err": {
+        const w = this.waiting.get(h.id);
+        if (!w) return;
+        clearTimeout(w.timer);
+        this.waiting.delete(h.id);
+        this.outbound.get(`q${h.id}`)?.cancel();
+        return w.reject(new ChannelError(h.message, "remote"));
+      }
+      case "abort":
+        return this.handling.get(h.id)?.abort();
+      case "data":
+        return this.inbound.get(h.s)?.push(payload);
+      case "end":
+        return this.inbound.get(h.s)?.end();
+      case "fail":
+        return this.inbound.get(h.s)?.fail(h.message);
+      case "more":
+        return this.outbound.get(h.s)?.grant(h.n);
+      case "cancel": {
+        this.outbound.get(h.s)?.cancel();
+        /* the response nobody reads any more: the handler stops too (an SSE stream leaves) */
+        if (h.s.startsWith("s")) this.handling.get(Number(h.s.slice(1)))?.abort();
+        return;
+      }
+    }
+  }
+
+  /** The socket closed: everything in flight fails. @param {string} [reason] */
+  close(reason = "o canal fechou") {
+    if (this.closed) return;
+    this.closed = true;
+    for (const w of this.waiting.values()) {
+      clearTimeout(w.timer);
+      w.reject(new ChannelError(reason, "closed"));
+    }
+    this.waiting.clear();
+    for (const i of [...this.inbound.values()]) i.fail(reason);
+    for (const o of [...this.outbound.values()]) o.cancel();
+    for (const ac of this.handling.values()) ac.abort();
+    this.handling.clear();
+  }
+
+  /** @param {{ id: number, method: string, path: string, headers: [string, string][], body: boolean }} h */
+  async handle(h) {
+    const ac = new AbortController();
+    this.handling.set(h.id, ac);
+    const done = () => this.handling.delete(h.id);
+    try {
+      if (!this.onRequest) throw new Error("este lado do canal não atende pedidos");
+      const body = h.body ? this.incoming(`q${h.id}`) : undefined;
+      const request = new Request(`http://runner${h.path}`, {
+        method: h.method,
+        headers: h.headers,
+        body,
+        signal: ac.signal,
+        // @ts-expect-error Node and Bun need it for a streaming request body
+        duplex: "half",
+      });
+      const res = await this.onRequest(request);
+      if (ac.signal.aborted) {
+        res.body?.cancel().catch(() => {});
+        return done();
+      }
+      const hasBody = !!res.body && !NO_BODY.has(res.status) && h.method !== "HEAD";
+      if (!hasBody) res.body?.cancel().catch(() => {});
+      this.frame({ t: "res", id: h.id, status: res.status, headers: [...res.headers], body: hasBody });
+      if (hasBody && res.body) this.pump(`s${h.id}`, res.body, done, !LIVE.test(res.headers.get("content-type") ?? ""));
+      else done();
+    } catch (e) {
+      done();
+      if (!ac.signal.aborted) this.frame({ t: "err", id: h.id, message: message(e) });
+    }
+  }
+
+  /** The receiving end of stream `key`, as a ReadableStream that grants credit as it is pulled.
+   *  @param {string} key */
+  incoming(key) {
+    const self = this;
+    /** @type {ReadableStreamDefaultController<Uint8Array>} */
+    let ctrl;
+    /** @type {(() => void) | null} */
+    let waiter = null;
+    let outstanding = 0;
+    const wake = () => {
+      const w = waiter;
+      waiter = null;
+      w?.();
+    };
+    const stream = new ReadableStream(
+      {
+        start(c) {
+          ctrl = c;
+        },
+        /* grant what the queue has room for, minus what is already on its way; then wait for a chunk,
+           so pull isn't called again in a loop */
+        pull(c) {
+          const want = (c.desiredSize ?? 1) - outstanding;
+          if (want > 0) {
+            outstanding += want;
+            self.frame({ t: "more", s: key, n: want });
+          }
+          return new Promise(r => {
+            waiter = () => r(undefined);
+          });
+        },
+        cancel() {
+          if (!self.inbound.delete(key)) return;
+          self.frame({ t: "cancel", s: key });
+          wake();
+        },
+      },
+      new CountQueuingStrategy({ highWaterMark: WINDOW }),
+    );
+    this.inbound.set(key, {
+      push: p => {
+        outstanding = Math.max(0, outstanding - 1);
+        ctrl.enqueue(p.slice());
+        wake();
+      },
+      end: () => {
+        this.inbound.delete(key);
+        ctrl.close();
+        wake();
+      },
+      fail: m => {
+        this.inbound.delete(key);
+        ctrl.error(new ChannelError(m, "remote"));
+        wake();
+      },
+    });
+    return stream;
+  }
+
+  /** Sends `body` as stream `key` as credit arrives. The source is read ahead (up to one frame): what
+   *  piles up while there is no credit goes as one frame. A bulk stream sends BULK_CHUNK frames, each
+   *  only once the socket's queue is under BULK_BACKLOG.
+   *  @param {string} key @param {ReadableStream} body @param {() => void} [onDone] @param {boolean} [bulk] */
+  pump(key, body, onDone, bulk = false) {
+    const reader = body.getReader();
+    const size = bulk ? BULK_CHUNK : CHUNK;
+    let credit = 0;
+    let cancelled = false;
+    let ended = false;
+    /** @type {string | null} */
+    let failed = null;
+    /** @type {Uint8Array[]} */
+    const queue = [];
+    let queued = 0;
+    /** @type {Record<"send" | "read", (() => void) | null>} */
+    const waiters = { send: null, read: null };
+    const wake = (/** @type {"send" | "read"} */ k) => {
+      const w = waiters[k];
+      waiters[k] = null;
+      w?.();
+    };
+    const sleep = (/** @type {"send" | "read"} */ k) => new Promise(r => (waiters[k] = () => r(undefined)));
+    /** the next frame: up to `size` bytes off the front of the queue */
+    const take = () => {
+      const n = Math.min(size, queued);
+      if (queue[0].byteLength === n) {
+        queued -= n;
+        return /** @type {Uint8Array} */ (queue.shift());
+      }
+      const out = new Uint8Array(n);
+      for (let o = 0; o < n; ) {
+        const head = queue[0];
+        const k = Math.min(head.byteLength, n - o);
+        out.set(head.subarray(0, k), o);
+        o += k;
+        if (k === head.byteLength) queue.shift();
+        else queue[0] = head.subarray(k);
+      }
+      queued -= n;
+      return out;
+    };
+    this.outbound.set(key, {
+      grant: n => {
+        credit += n;
+        wake("send");
+      },
+      cancel: () => {
+        cancelled = true;
+        reader.cancel().catch(() => {});
+        wake("send");
+        wake("read");
+      },
+    });
+    /* the reader: keeps up to one frame waiting */
+    (async () => {
+      try {
+        for (;;) {
+          while ((queued >= size || queue.length >= MAX_PIECES) && !cancelled) await sleep("read");
+          if (cancelled) return;
+          const { done, value } = await reader.read();
+          if (cancelled) return;
+          if (done) break;
+          const bytes =
+            typeof value === "string"
+              ? encoder.encode(value)
+              : new Uint8Array(value.buffer ?? value, value.byteOffset ?? 0, value.byteLength);
+          if (bytes.byteLength) {
+            queue.push(bytes);
+            queued += bytes.byteLength;
+          }
+          wake("send");
+        }
+        ended = true;
+      } catch (e) {
+        failed = message(e);
+      }
+      wake("send");
+    })();
+    /* the sender: one frame per credit */
+    (async () => {
+      try {
+        for (;;) {
+          while (!cancelled && !(queued > 0 && credit > 0) && !(queued === 0 && (ended || failed !== null)))
+            await sleep("send");
+          if (cancelled) return;
+          if (queued === 0) {
+            if (failed !== null) this.frame({ t: "fail", s: key, message: failed });
+            else this.frame({ t: "end", s: key });
+            return;
+          }
+          if (bulk)
+            while (!cancelled && this.backlog() >= BULK_BACKLOG) await new Promise(r => setTimeout(r, BULK_POLL_MS));
+          if (cancelled) return;
+          credit--;
+          this.frame({ t: "data", s: key }, take());
+          wake("read");
+        }
+      } catch (e) {
+        if (!cancelled) this.frame({ t: "fail", s: key, message: message(e) });
+      } finally {
+        this.outbound.delete(key);
+        onDone?.();
+      }
+    })();
+  }
+}

package/tools/lib/claude-settings.mjs

@@ -0,0 +1,67 @@
+/* The permission rules the plugin's skills need in the user's Claude Code settings (quick test 1 in
+   docs/specs/phase-2-plugin-cli.md): a skill's `!` line runs only when a rule allows it, the served skills
+   call `<cli> run …` through Bash, and their sibling files sit in a temporary folder outside the working
+   one. Written only with the user's yes (the MCP's omni_allow_skills, after Claude asks, or `omni setup`).
+
+   The settings file is $CLAUDE_CONFIG_DIR/settings.json, else ~/.claude/settings.json. The rules are added
+   to permissions.allow; nothing else in the file changes. */
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { CLI_COMMAND } from "./cli.mjs";
+
+export const settingsFile = () => join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "settings.json");
+
+/** the rules, for this CLI command and this machine's temporary folder (both spellings of it on macOS) */
+export function skillRules(cli = CLI_COMMAND) {
+  const tmp = tmpdir();
+  let real = tmp;
+  try {
+    real = realpathSync(tmp);
+  } catch {
+    /* keep the plain one */
+  }
+  return [
+    `Bash(${cli} skill *)`,
+    `Bash(${cli} run *)`,
+    ...[...new Set([tmp, real])].map(dir => `Read(/${dir}/omni-skills/**)`),
+  ];
+}
+
+/** @param {string} file @returns {any} */
+function read(file) {
+  if (!existsSync(file)) return {};
+  return JSON.parse(readFileSync(file, "utf8"));
+}
+
+/** the rules still missing from the settings  @param {{ file?: string, cli?: string }} [o] */
+export function missingRules({ file = settingsFile(), cli = CLI_COMMAND } = {}) {
+  let allow = [];
+  try {
+    allow = read(file)?.permissions?.allow ?? [];
+  } catch {
+    allow = [];
+  }
+  return skillRules(cli).filter(r => !allow.includes(r));
+}
+
+/** adds the missing rules; returns the ones it added  @param {{ file?: string, cli?: string }} [o] */
+export function allowSkillRules({ file = settingsFile(), cli = CLI_COMMAND } = {}) {
+  let settings;
+  try {
+    settings = read(file);
+  } catch {
+    throw new Error(`não consegui ler ${file}: o JSON está quebrado, corrija antes`);
+  }
+  const allow = Array.isArray(settings?.permissions?.allow) ? settings.permissions.allow : [];
+  const added = skillRules(cli).filter(r => !allow.includes(r));
+  if (!added.length) return [];
+  settings.permissions = { ...(settings.permissions ?? {}), allow: [...allow, ...added] };
+  mkdirSync(dirname(file), { recursive: true });
+  /* write then rename, so a crash never leaves the user's settings half written */
+  const tmp = `${file}.omni-${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}\n`);
+  renameSync(tmp, file);
+  return added;
+}

package/tools/lib/cli.mjs

@@ -0,0 +1,9 @@
+/* The `omni` CLI's name and where it talks to, in one place: the plugin's headers, hook and MCP, the
+   permission rules and the served skills all call the CLI the same way (docs/specs/phase-2-plugin-cli.md).
+   OMNI_CLI_COMMAND points them at another command, to try a local build before publishing
+   (e.g. `node /path/to/tools/omni.mjs`). */
+
+export const PACKAGE = "@crievo/omni";
+export const CLI_COMMAND = process.env.OMNI_CLI_COMMAND || `npx -y ${PACKAGE}`;
+/* the hosted studio a fresh workspace points at */
+export const STUDIO_URL = "https://omni.crievo.com";