kijito-tools 0.2.0

package/providers/codex/wake-helper/mock-daemon.mjs

@@ -0,0 +1,64 @@
+// Minimal mock of the codex app-server DAEMON control socket for helper integration tests.
+// Speaks the measured 0.147 transport — WEBSOCKET over the unix socket (handshake, then
+// JSON-RPC as one message per text frame) — and the measured methods: initialize,
+// thread/resume, turn/start; pushes thread/status/changed notifications on demand.
+// Test-only — the gate-4 battery runs against the REAL daemon; this exists so the run loop's
+// logic (defer-until-idle, loud exits, gasp) is proven on the same transport first.
+import net from "node:net";
+import fs from "node:fs";
+import { acceptWsUds } from "./ws-uds.mjs";
+
+export class MockDaemon {
+  constructor(sockPath, { threadId = "T1", initialStatus = "idle", failResume = false } = {}) {
+    this.sockPath = sockPath;
+    this.threadId = threadId;
+    this.status = initialStatus;
+    this.failResume = failResume;
+    this.calls = [];
+    this.conns = new Set();
+    this.turnSeq = 0;
+  }
+
+  listen() {
+    try { fs.unlinkSync(this.sockPath); } catch { /* fresh */ }
+    this.server = net.createServer(async (sock) => {
+      const conn = await acceptWsUds(sock, {
+        onText: (text, c) => this.handle(c, JSON.parse(text)),
+        onClose: () => this.conns.delete(conn),
+      }).catch(() => null);
+      if (conn) this.conns.add(conn);
+    });
+    return new Promise((resolve) => this.server.listen(this.sockPath, resolve));
+  }
+
+  handle(conn, msg) {
+    this.calls.push(msg);
+    if (msg.id === undefined) return; // notification (e.g. initialized)
+    const reply = (result) => conn.sendText(JSON.stringify({ jsonrpc: "2.0", id: msg.id, result }));
+    const fail = (message) => conn.sendText(JSON.stringify({ jsonrpc: "2.0", id: msg.id, error: { code: -32000, message } }));
+    if (msg.method === "initialize") return reply({});
+    if (msg.method === "thread/resume") {
+      if (this.failResume) return fail("thread not found");
+      return reply({ thread: { id: this.threadId, status: { type: this.status } } });
+    }
+    if (msg.method === "turn/start") {
+      if (this.status !== "idle") return fail("thread busy");
+      this.turnSeq += 1;
+      return reply({ turn: { id: `turn-${this.turnSeq}` } });
+    }
+    return fail(`unknown method ${msg.method}`);
+  }
+
+  setStatus(type) {
+    this.status = type;
+    const note = JSON.stringify({ jsonrpc: "2.0", method: "thread/status/changed", params: { threadId: this.threadId, status: { type } } });
+    for (const conn of this.conns) conn.sendText(note);
+  }
+
+  turnStarts() { return this.calls.filter((c) => c.method === "turn/start"); }
+
+  close() {
+    for (const conn of this.conns) conn.destroy();
+    return new Promise((resolve) => this.server.close(resolve));
+  }
+}

package/providers/codex/wake-helper/status-probe.mjs

@@ -0,0 +1,45 @@
+// One-shot leg-(ii) instrument: what does a SECOND client see when it resumes a thread
+// mid-turn? Prints the status thread/resume returns, plus any thread/status/changed
+// notifications observed in a short listen window. Read-only.
+import { connectWsUds } from "./ws-uds.mjs";
+
+const [sock, threadId, listenMsArg] = process.argv.slice(2);
+if (!sock || !threadId) { process.stderr.write("usage: status-probe.mjs <sock> <threadId> [listenMs]\n"); process.exit(2); }
+const listenMs = Number(listenMsArg ?? 0);
+
+const pending = new Map();
+let nextId = 1;
+let conn;
+const notes = [];
+
+function send(method, params) {
+  return new Promise((resolve, reject) => {
+    const id = nextId++;
+    pending.set(id, { resolve, reject });
+    conn.sendText(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+    setTimeout(() => { if (pending.has(id)) { pending.delete(id); reject(new Error(`timeout:${method}`)); } }, 10_000);
+  });
+}
+
+conn = await connectWsUds(sock, {
+  onText: (text) => {
+    let msg; try { msg = JSON.parse(text); } catch { return; }
+    if (msg.id !== undefined && pending.has(msg.id)) {
+      const p = pending.get(msg.id); pending.delete(msg.id);
+      if (msg.error) p.reject(new Error(msg.error.message ?? "rpc-error")); else p.resolve(msg.result);
+    } else if (msg.method === "thread/status/changed") {
+      notes.push({ at: new Date().toISOString(), params: msg.params });
+    }
+  },
+  onClose: () => {},
+});
+
+await send("initialize", { clientInfo: { name: "g4-status-probe", title: "g4 status probe", version: "1" }, capabilities: { experimentalApi: true } });
+conn.sendText(JSON.stringify({ jsonrpc: "2.0", method: "initialized" }));
+const opened = await send("thread/resume", { threadId });
+process.stdout.write(JSON.stringify({ at: new Date().toISOString(), resumeStatus: opened?.thread?.status ?? null }) + "\n");
+if (listenMs > 0) {
+  await new Promise((r) => setTimeout(r, listenMs));
+  process.stdout.write(JSON.stringify({ notificationsObserved: notes }) + "\n");
+}
+process.exit(0);

package/providers/codex/wake-helper/ws-uds.mjs

@@ -0,0 +1,153 @@
+// Minimal RFC 6455 WebSocket over a unix-domain socket — zero dependencies, exactly what the
+// codex app-server daemon control socket speaks (measured at source, rust-v0.147.0:
+// tokio_tungstenite accept_async on the UnixStream; clients dial with handshake URL
+// ws://localhost/rpc and exchange JSON-RPC as text frames; filesystem 0600 is the auth).
+//
+// Scope is deliberately narrow: text frames, unfragmented (our JSON-RPC messages are small),
+// ping->pong, clean close. Anything outside that surface errors loudly rather than guessing.
+import crypto from "node:crypto";
+import net from "node:net";
+
+const WS_MAGIC = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+export const HANDSHAKE_PATH = "/rpc";
+
+function acceptKeyFor(key) {
+  return crypto.createHash("sha1").update(key + WS_MAGIC).digest("base64");
+}
+
+// ---------- framing ----------
+
+export function encodeFrame(opcode, payload, mask) {
+  const len = payload.length;
+  let header;
+  if (len < 126) header = Buffer.from([0x80 | opcode, (mask ? 0x80 : 0) | len]);
+  else if (len < 65_536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x80 | opcode; header[1] = (mask ? 0x80 : 0) | 126; header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x80 | opcode; header[1] = (mask ? 0x80 : 0) | 127; header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  if (!mask) return Buffer.concat([header, payload]);
+  const key = crypto.randomBytes(4);
+  const masked = Buffer.from(payload);
+  for (let i = 0; i < masked.length; i += 1) masked[i] ^= key[i % 4];
+  return Buffer.concat([header, key, masked]);
+}
+
+// Incremental decoder: feed bytes, yields {opcode, payload} frames.
+export class FrameDecoder {
+  constructor() { this.buf = Buffer.alloc(0); }
+  push(chunk) {
+    this.buf = Buffer.concat([this.buf, chunk]);
+    const frames = [];
+    for (;;) {
+      if (this.buf.length < 2) break;
+      const fin = (this.buf[0] & 0x80) !== 0;
+      const opcode = this.buf[0] & 0x0f;
+      const masked = (this.buf[1] & 0x80) !== 0;
+      let len = this.buf[1] & 0x7f;
+      let off = 2;
+      if (len === 126) { if (this.buf.length < 4) break; len = this.buf.readUInt16BE(2); off = 4; }
+      else if (len === 127) {
+        if (this.buf.length < 10) break;
+        const big = this.buf.readBigUInt64BE(2);
+        if (big > BigInt(64 * 1024 * 1024)) throw new Error("ws frame too large");
+        len = Number(big); off = 10;
+      }
+      const maskLen = masked ? 4 : 0;
+      if (this.buf.length < off + maskLen + len) break;
+      if (!fin) throw new Error("fragmented ws frames unsupported");
+      let payload = this.buf.subarray(off + maskLen, off + maskLen + len);
+      if (masked) {
+        const key = this.buf.subarray(off, off + 4);
+        payload = Buffer.from(payload);
+        for (let i = 0; i < payload.length; i += 1) payload[i] ^= key[i % 4];
+      }
+      frames.push({ opcode, payload: Buffer.from(payload) });
+      this.buf = this.buf.subarray(off + maskLen + len);
+    }
+    return frames;
+  }
+}
+
+// ---------- shared per-connection wiring ----------
+
+function wire(sock, { isClient, onText, onClose }) {
+  const decoder = new FrameDecoder();
+  const conn = {
+    sendText: (text) => sock.write(encodeFrame(0x1, Buffer.from(text, "utf8"), isClient)),
+    close: () => { try { sock.write(encodeFrame(0x8, Buffer.alloc(0), isClient)); } catch { /* gone */ } sock.end(); },
+    destroy: () => sock.destroy(),
+  };
+  sock.on("data", (chunk) => {
+    let frames;
+    try { frames = decoder.push(chunk); } catch (error) { sock.destroy(error); return; }
+    for (const frame of frames) {
+      if (frame.opcode === 0x1) onText(frame.payload.toString("utf8"), conn);
+      else if (frame.opcode === 0x9) sock.write(encodeFrame(0xa, frame.payload, isClient)); // ping->pong
+      else if (frame.opcode === 0x8) { try { sock.write(encodeFrame(0x8, Buffer.alloc(0), isClient)); } catch { /* gone */ } sock.end(); }
+      // 0xa pong and binary 0x2 ignored — nothing on this surface sends them meaningfully.
+    }
+  });
+  sock.on("close", () => onClose?.());
+  sock.on("error", () => { /* close event follows; onClose reports */ });
+  return conn;
+}
+
+// ---------- client ----------
+
+export function connectWsUds(sockPath, { path = HANDSHAKE_PATH, timeoutMs = 10_000, onText, onClose } = {}) {
+  return new Promise((resolve, reject) => {
+    const sock = net.createConnection(sockPath);
+    const timer = setTimeout(() => { sock.destroy(); reject(new Error("ws-handshake-timeout")); }, timeoutMs);
+    sock.once("error", (error) => { clearTimeout(timer); reject(error); });
+    sock.once("connect", () => {
+      const key = crypto.randomBytes(16).toString("base64");
+      sock.write(`GET ${path} HTTP/1.1\r\nHost: localhost\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Key: ${key}\r\nSec-WebSocket-Version: 13\r\n\r\n`);
+      let head = "";
+      const onHead = (chunk) => {
+        head += chunk.toString("latin1");
+        const end = head.indexOf("\r\n\r\n");
+        if (end === -1) {
+          if (head.length > 16_384) { sock.destroy(); clearTimeout(timer); reject(new Error("ws-handshake-oversized")); }
+          return;
+        }
+        sock.removeListener("data", onHead);
+        const header = head.slice(0, end);
+        const rest = Buffer.from(head.slice(end + 4), "latin1");
+        if (!/^HTTP\/1\.1 101 /.test(header)) { sock.destroy(); clearTimeout(timer); reject(new Error(`ws-handshake-rejected: ${header.split("\r\n")[0]}`)); return; }
+        const accept = /sec-websocket-accept: *([^\r\n]+)/i.exec(header)?.[1];
+        if (accept !== acceptKeyFor(key)) { sock.destroy(); clearTimeout(timer); reject(new Error("ws-accept-mismatch")); return; }
+        clearTimeout(timer);
+        const conn = wire(sock, { isClient: true, onText, onClose });
+        if (rest.length) sock.emit("data", rest);
+        resolve(conn);
+      };
+      sock.on("data", onHead);
+    });
+  });
+}
+
+// ---------- server-accept (mock daemon / tests) ----------
+
+export function acceptWsUds(sock, { onText, onClose }) {
+  return new Promise((resolve, reject) => {
+    let head = "";
+    const onHead = (chunk) => {
+      head += chunk.toString("latin1");
+      const end = head.indexOf("\r\n\r\n");
+      if (end === -1) return;
+      sock.removeListener("data", onHead);
+      const key = /sec-websocket-key: *([^\r\n]+)/i.exec(head.slice(0, end))?.[1];
+      if (!key) { sock.destroy(); reject(new Error("ws-server: no key")); return; }
+      sock.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${acceptKeyFor(key)}\r\n\r\n`);
+      const rest = Buffer.from(head.slice(end + 4), "latin1");
+      const conn = wire(sock, { isClient: false, onText, onClose });
+      if (rest.length) sock.emit("data", rest);
+      resolve(conn);
+    };
+    sock.on("data", onHead);
+    sock.once("error", reject);
+  });
+}

package/providers/monitor/.github/workflows/publish-npm.yml

@@ -0,0 +1,38 @@
+name: publish-npm
+
+# Publishes the kijito-inbox-monitor npm SIGNPOST package on a version tag, using Trusted
+# Publishing (OIDC). The npm package is not a real installer: it points users at the Python
+# package on PyPI (see bin/cli.js). No NPM_TOKEN is stored; npm exchanges a short-lived
+# workflow credential and attaches provenance automatically.
+#
+# Canonical form per docs.npmjs.com/trusted-publishers: Node 24 (bundles npm >= 11.5.1, which
+# trusted publishing requires) + registry-url + `npm publish` with NO NODE_AUTH_TOKEN. There
+# are zero deps and no lockfile, so we skip `npm ci`.
+#
+# Trusted Publisher config on npmjs.com (package -> Settings -> Trusted Publisher) must match
+# EXACTLY (case-sensitive): Organization/user "KijitoAI", Repository "kijito-inbox-monitor",
+# Workflow filename "publish-npm.yml" (filename only, WITH .yml, not a path), Environment blank,
+# and Allowed actions must include "npm publish". A mismatch on any field fails with E404
+# "could not be found or you do not have permission".
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  id-token: write   # required for Trusted Publishing
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"        # bundles npm >= 11.5.1, required for OIDC trusted publishing
+          registry-url: "https://registry.npmjs.org"
+      - run: npm --version
+      # Zero runtime deps and no lockfile, so no `npm ci`. There is no postinstall hook
+      # (npm v12 disables install lifecycle scripts by default, and that pattern is the worm).
+      - run: npm publish --access public

package/providers/monitor/.github/workflows/publish-pypi.yml

@@ -0,0 +1,30 @@
+name: publish-pypi
+
+# Publishes kijito-inbox-monitor to PyPI on a version tag, using Trusted Publishing (OIDC).
+# No PyPI API token is stored: PyPI exchanges a short-lived OIDC credential and the publish
+# action attaches PEP 740 attestations automatically. Configure the trusted publisher once
+# on pypi.org first: pypi.org -> the project -> Publishing -> add this repo + this workflow
+# file + the "pypi" environment.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  id-token: write   # required for Trusted Publishing
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kijito-inbox-monitor
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pipx run build              # builds sdist + wheel into dist/
+      - run: pipx run twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1   # v1.11+ attaches attestations by default