hitloop 0.0.0-stage → 0.1.1

package/dist/hooks.js

@@ -0,0 +1,65 @@
+// The Claude Code hooks hitl can add to a project (opt-in): one tells Claude what the human said whenever they send it a
+// message; the other stops Claude finishing while an approval or a blocking question is waiting. They live in the
+// project's .claude/settings.json; `hitl hooks`, `hitl init --hook/--stop-hook` and the page's settings change them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** How Claude Code should start hitl: through npx once it's published, else this copy. */
+export function launcher() {
+    const cli = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'cli.js');
+    if (/[\\/]_npx[\\/]|[\\/]node_modules[\\/]hitloop[\\/]/.test(cli)) {
+        return process.platform === 'win32'
+            ? { command: 'cmd', args: ['/c', 'npx', '-y', 'hitloop@latest'], line: 'cmd /c npx -y hitloop@latest' }
+            : { command: 'npx', args: ['-y', 'hitloop@latest'], line: 'npx -y hitloop@latest' };
+    }
+    return { command: process.execPath, args: [cli], line: `"${process.execPath}" "${cli}"` };
+}
+export function setHooks(root, want) {
+    const file = path.join(root, '.claude', 'settings.json');
+    let settings = {};
+    try {
+        settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        settings = {};
+    }
+    const l = launcher();
+    const out = [];
+    const isOurs = (cmd, which) => /hitl/.test(cmd) && new RegExp(` hook${which === 'stop' ? ' stop' : '( prompt)?'}$`).test(cmd);
+    const apply = (event, which, on, label) => {
+        if (on === undefined)
+            return;
+        settings.hooks ??= {};
+        const list = (settings.hooks[event] ??= []);
+        const has = list.some((h) => h.hooks?.some((x) => isOurs(x.command, which)));
+        if (on && !has) {
+            list.push({ hooks: [{ type: 'command', command: `${l.line} hook ${which}` }] });
+            out.push(`✓ ${label}: on`);
+        }
+        else if (!on && has) {
+            settings.hooks[event] = list.map((h) => ({ ...h, hooks: h.hooks.filter((x) => !isOurs(x.command, which)) })).filter((h) => h.hooks.length);
+            if (!settings.hooks[event]?.length)
+                delete settings.hooks[event];
+            out.push(`✓ ${label}: off`);
+        }
+        else
+            out.push(`✓ ${label}: already ${on ? 'on' : 'off'}`);
+    };
+    apply('UserPromptSubmit', 'prompt', want.prompt, 'News hook (tells Claude what you said when you send a message)');
+    apply('Stop', 'stop', want.stop, "Stop hook (Claude can't finish while an approval or blocking question waits)");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+    return out;
+}
+/** which of hitl's hooks are on in a project */
+export function hookStatus(root) {
+    let s = {};
+    try {
+        s = JSON.parse(fs.readFileSync(path.join(root, '.claude', 'settings.json'), 'utf8'));
+    }
+    catch {
+        s = {};
+    }
+    const has = (ev, re) => !!s.hooks?.[ev]?.some((x) => x.hooks?.some((c) => /hitl/.test(c.command) && re.test(c.command)));
+    return { prompt: has('UserPromptSubmit', / hook( prompt)?$/), stop: has('Stop', / hook stop$/) };
+}

package/dist/http.js

@@ -0,0 +1,81 @@
+import crypto from 'node:crypto';
+import { StoreError } from './hub/atomic.js';
+export function json(res, code, data) {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' }).end(JSON.stringify(data));
+}
+export function text(res, body, type = 'text/plain; charset=utf-8') {
+    res.writeHead(200, { 'content-type': type, 'cache-control': 'no-store' }).end(body);
+}
+export async function body(req, max = 1_000_000) {
+    if (!String(req.headers['content-type'] ?? '').includes('application/json'))
+        throw new StoreError('Send JSON');
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        const b = Buffer.isBuffer(c) ? c : Buffer.from(String(c));
+        size += b.length;
+        if (size > max)
+            throw new StoreError('Too large');
+        chunks.push(b);
+    }
+    const data = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        throw new StoreError('Send a JSON object');
+    return Object.fromEntries(Object.entries(data));
+}
+export const disposition = (name) => `attachment; filename="${name.replace(/[^\x20-\x7e]|["\\]/g, '_')}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+export const bearer = (req) => /^Bearer (.+)$/i.exec(String(req.headers.authorization ?? ''))?.[1];
+export const cookie = (req, name) => {
+    for (const part of String(req.headers.cookie ?? '').split(';')) {
+        const [k, ...v] = part.trim().split('=');
+        if (k === name)
+            return decodeURIComponent(v.join('='));
+    }
+    return undefined;
+};
+export function same(a, b) {
+    const x = crypto.createHash('sha256').update(a).digest();
+    const y = crypto.createHash('sha256').update(b).digest();
+    return crypto.timingSafeEqual(x, y);
+}
+export const str = (v) => (typeof v === 'string' ? v : '');
+export const posInt = (v) => (typeof v === 'number' && Number.isInteger(v) && v > 0 ? v : undefined);
+export const strList = (v) => (Array.isArray(v) ? v.map(String) : typeof v === 'string' && v ? [v] : []);
+/** a picture comment's marks from a request: the area, the strokes, and the marked-up picture (a PNG data URL) */
+export function imageMarks(b) {
+    const out = {};
+    const a = b['area'];
+    if (a && typeof a === 'object' && !Array.isArray(a)) {
+        const r = Object.fromEntries(Object.entries(a));
+        const n = (k) => (typeof r[k] === 'number' && Number.isFinite(r[k]) && Number(r[k]) >= 0 ? Math.round(Number(r[k])) : undefined);
+        const [x, y, w, h] = [n('x'), n('y'), n('w'), n('h')];
+        if (x !== undefined && y !== undefined && w && h)
+            out.area = { x, y, w, h };
+    }
+    const s = b['strokes'];
+    if (Array.isArray(s)) {
+        let budget = 20_000;
+        const strokes = s
+            .filter((st) => Array.isArray(st))
+            .map((st) => st.filter((v) => typeof v === 'number' && v >= 0 && v <= 1).map((v) => Math.round(v * 10000) / 10000))
+            .filter((st) => st.length >= 2 && st.length % 2 === 0 && (budget -= st.length) >= 0);
+        if (strokes.length)
+            out.strokes = strokes;
+    }
+    const snap = typeof b['snapshot'] === 'string' ? /^data:image\/png;base64,([A-Za-z0-9+/=]+)$/.exec(b['snapshot']) : null;
+    if (snap && out.strokes) {
+        const buf = Buffer.from(snap[1] ?? '', 'base64');
+        if (buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+            out.snapshot = buf;
+            out.snapshotUrl = String(b['snapshot']);
+        }
+    }
+    return out;
+}
+/** photos attached to a comment: image data URLs only */
+export function photos(b) {
+    const p = b['photos'];
+    if (!Array.isArray(p))
+        return [];
+    return p.filter((x) => typeof x === 'string' && /^data:image\/(png|jpeg|webp|gif|heic|avif);base64,[A-Za-z0-9+/=]+$/.test(x)).slice(0, 8);
+}

package/dist/hub/atomic.js

@@ -0,0 +1,77 @@
+// Safe writes from many processes at once: an atomic rename, under a lock file.
+import fs from 'node:fs';
+import path from 'node:path';
+export class StoreError extends Error {
+}
+export const stripBom = (s) => (s.charCodeAt(0) === 0xfeff ? s.slice(1) : s);
+export function writeAtomic(file, text) {
+    const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    fs.writeFileSync(tmp, text);
+    for (let i = 0;; i++) {
+        try {
+            fs.renameSync(tmp, file);
+            return;
+        }
+        catch (e) {
+            // Windows: a reader holding the file open makes rename fail for a moment
+            if (i >= 20) {
+                fs.rmSync(tmp, { force: true });
+                throw e;
+            }
+            sleep(25);
+        }
+    }
+}
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Run fn holding <file>.lock (made with O_EXCL; a lock older than 10 s is taken as abandoned). */
+export function withLock(file, fn) {
+    const lock = file + '.lock';
+    const until = Date.now() + 8000;
+    for (;;) {
+        try {
+            fs.writeFileSync(lock, String(process.pid), { flag: 'wx' });
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > 10_000)
+                    fs.rmSync(lock, { force: true });
+            }
+            catch {
+                // gone already
+            }
+            if (Date.now() > until)
+                throw new StoreError(`${path.basename(file)} is locked by another process`);
+            sleep(15);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.rmSync(lock, { force: true });
+    }
+}
+/** .hitl/README.md: what the folder holds (written once). */
+export function ensureReadme(dir) {
+    const file = path.join(dir, 'README.md');
+    if (fs.existsSync(file))
+        return;
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, HITL_README);
+}
+const HITL_README = `# hitl: Human In The Loop
+
+What an agent asked, showed or sent for review in this project, and what the human said back.
+Open it with \`npx hitloop\` (the links it prints work on a phone too). What's new for the agent: \`npx hitloop news\`.
+
+- \`questions/<id>.json\`: question sets (an agent writes these; the format: \`npx hitloop schema questions\`).
+- \`reviews/<id>.json\`: things shown for review or approval (an agent writes these; \`npx hitloop schema reviews\`).
+- \`answers/<id>.json\` and \`.md\`: the human's answers, verdicts and comments, one file per question set or review.
+- \`notes/\`: notes from the human on files, lines and picture areas (notes.json, NOTES.md, images/).
+- \`media/\`: pictures an agent passed as data, and photos the human attached.
+`;

package/dist/hub/notify.js

@@ -0,0 +1,239 @@
+// Push notifications to your phone when an agent asks for something: through ntfy (a push app for Android and iOS;
+// the hub posts to your private topic) or any webhook (Pushover, Discord, Home Assistant, …). Changes are batched: an
+// agent adding 50 questions over a minute makes one notification, sent once it has been quiet for a while. An approval
+// is someone waiting at a gate, so it goes out within a couple of seconds.
+//
+// Web Push isn't used: a phone only allows it on HTTPS pages, and hitl is opened over plain http on the LAN.
+import os from 'node:os';
+import { userConfig, lanAddresses } from './registry.js';
+import { allQuestions, visibility, isDone } from '../q/model.js';
+export const notifyConfig = (cfg = userConfig()) => (cfg.notify && typeof cfg.notify === 'object' ? cfg.notify : {});
+export const notifyEnabled = (n) => !!(n.ntfy || n.webhook);
+export class Notifier {
+    project;
+    port;
+    token;
+    base;
+    log;
+    seen = new Map();
+    pending = new Map();
+    started = Date.now();
+    constructor(project, port, token, base, log = () => undefined) {
+        this.project = project;
+        this.port = port;
+        this.token = token;
+        this.base = base;
+        this.log = log;
+    }
+    state(p, kind, id) {
+        if (kind === 'questions') {
+            const l = p.questions.load(id);
+            if (!l)
+                return undefined;
+            const af = p.questions.answers(id);
+            let agentMessages = 0;
+            for (const list of Object.values(af.threads))
+                for (const m of list)
+                    if (m.from === 'agent')
+                        agentMessages++;
+            return { things: new Set(allQuestions(l.set).map((q) => q.id)), agentMessages };
+        }
+        if (kind === 'review') {
+            const l = p.reviews.load(id);
+            if (!l)
+                return undefined;
+            const fb = p.reviews.feedback(id);
+            let agentMessages = 0;
+            for (const c of fb.comments)
+                agentMessages += (c.from === 'agent' ? 1 : 0) + c.replies.filter((r) => r.from === 'agent').length;
+            // "@open": the review is (again) open, so an approval asked again counts as new
+            return { things: new Set([...l.review.items.map((i) => i.id), `@${l.review.status}`]), agentMessages };
+        }
+        let agentMessages = 0;
+        for (const c of p.notes.all())
+            agentMessages += (c.replies ?? []).filter((r) => r.from === 'agent' || r.author === 'agent').length;
+        return { things: new Set(), agentMessages };
+    }
+    created(p, kind, id) {
+        const c = kind === 'questions' ? p.questions.load(id)?.set.created : kind === 'review' ? p.reviews.load(id)?.review.created : '';
+        return Date.parse(c ?? '') || 0;
+    }
+    /** What's there now counts as seen (on start). */
+    baseline(key) {
+        const p = this.project(key);
+        if (!p)
+            return;
+        for (const id of p.questions.ids())
+            this.keep(key, p, 'questions', id);
+        for (const id of p.reviews.ids())
+            this.keep(key, p, 'review', id);
+        this.keep(key, p, 'notes', 'notes');
+    }
+    keep(key, p, kind, id) {
+        const s = this.state(p, kind, id);
+        if (s)
+            this.seen.set(`${key}/${kind}/${id}`, s);
+    }
+    /** Something changed in a request: queue what's new. */
+    observe(key, kind, id) {
+        const k = `${key}/${kind}/${id}`;
+        const p = this.project(key);
+        if (!p)
+            return;
+        const now = this.state(p, kind, id);
+        if (!now)
+            return;
+        let was = this.seen.get(k);
+        if (!was)
+            was = this.created(p, kind, id) >= this.started - 5000 ? { things: new Set(), agentMessages: 0 } : now;
+        const fresh = [...now.things].filter((t) => !was.things.has(t) && t !== '@closed');
+        const replies = Math.max(0, now.agentMessages - was.agentMessages);
+        this.seen.set(k, now);
+        if (!fresh.length && !replies)
+            return;
+        const cfg = notifyConfig();
+        if (!notifyEnabled(cfg))
+            return;
+        const pend = this.pending.get(k) ?? { fresh: new Set(), replies: 0, first: Date.now() };
+        for (const t of fresh)
+            pend.fresh.add(t);
+        pend.replies += cfg.replies === false ? 0 : replies;
+        if (!pend.fresh.size && !pend.replies)
+            return;
+        this.pending.set(k, pend);
+        clearTimeout(pend.timer);
+        const quiet = Math.max(1, cfg.quietSeconds ?? 20) * 1000;
+        const isGate = kind === 'review' && p.reviews.load(id)?.review.mode === 'approve';
+        const wait = isGate ? 1500 : Math.min(quiet, Math.max(0, pend.first + 120_000 - Date.now()));
+        pend.timer = setTimeout(() => void this.flush(key, kind, id), wait);
+        pend.timer.unref?.();
+    }
+    async flush(key, kind, id) {
+        const k = `${key}/${kind}/${id}`;
+        const pend = this.pending.get(k);
+        this.pending.delete(k);
+        const p = this.project(key);
+        if (!pend || !p)
+            return;
+        const notice = this.compose(p, key, kind, id, pend);
+        if (!notice)
+            return;
+        try {
+            await send(notifyConfig(), notice);
+            this.log(`notified: ${notice.title}`);
+        }
+        catch (e) {
+            this.log(`couldn't notify: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    compose(p, key, kind, id, pend) {
+        const base = { url: this.link(key, kind, id), project: key, request: id, newQuestions: 0, newItems: 0, approval: false, blocking: 0, replies: pend.replies };
+        const replyText = pend.replies ? `${pend.replies} repl${pend.replies === 1 ? 'y' : 'ies'} from the agent` : '';
+        if (kind === 'questions') {
+            const l = p.questions.load(id);
+            if (!l)
+                return undefined;
+            const af = p.questions.answers(id);
+            const vis = visibility(l.set, af.answers);
+            const fresh = allQuestions(l.set).filter((q) => pend.fresh.has(q.id) && vis.question(q.id));
+            const blocking = fresh.filter((q) => q.priority === 'blocking' && !isDone(af.answers[q.id])).length;
+            if (!fresh.length && !pend.replies)
+                return undefined;
+            const first = fresh[0];
+            return {
+                ...base,
+                kind: 'questions',
+                title: `${l.set.title}: ${[fresh.length ? `${fresh.length} new question${fresh.length === 1 ? '' : 's'}` : '', replyText].filter(Boolean).join(', ')}`,
+                message: [
+                    blocking ? `${blocking} blocking: the agent is waiting on ${blocking === 1 ? 'it' : 'them'}.` : '',
+                    first ? `“${first.question.replace(/\s+/g, ' ').slice(0, 120)}”${fresh.length > 1 ? ` and ${fresh.length - 1} more` : ''}` : 'Tap to read.',
+                    `${key} · ${id}`,
+                ]
+                    .filter(Boolean)
+                    .join('\n'),
+                newQuestions: fresh.length,
+                blocking,
+            };
+        }
+        if (kind === 'review') {
+            const l = p.reviews.load(id);
+            if (!l)
+                return undefined;
+            const r = l.review;
+            const items = r.items.filter((i) => pend.fresh.has(i.id));
+            const gate = r.mode === 'approve';
+            const asked = gate && pend.fresh.has('@open');
+            if (!items.length && !pend.replies && !asked)
+                return undefined;
+            const what = gate ? 'asks for your OK' : `${items.length} thing${items.length === 1 ? '' : 's'} to ${r.mode === 'show' ? 'look at' : 'review'}`;
+            return {
+                ...base,
+                kind: gate ? 'approve' : 'review',
+                title: `${r.title}: ${[items.length || asked ? what : '', replyText].filter(Boolean).join(', ')}`,
+                message: [
+                    r.from ? `From ${r.from}.` : '',
+                    gate ? 'Approve or refuse: the agent is waiting.' : items[0] ? `“${items[0].title.slice(0, 120)}”${items.length > 1 ? ` and ${items.length - 1} more` : ''}` : 'Tap to read.',
+                    `${key} · ${id}`,
+                ]
+                    .filter(Boolean)
+                    .join('\n'),
+                newItems: items.length,
+                approval: gate,
+                blocking: gate ? 1 : 0,
+            };
+        }
+        if (!pend.replies)
+            return undefined;
+        return { ...base, kind: 'notes', title: `${key}: ${replyText} on your notes`, message: 'Tap to read.' };
+    }
+    link(key, kind, id) {
+        const hash = kind === 'notes' ? `#/p/${encodeURIComponent(key)}/notes` : `#/p/${encodeURIComponent(key)}/${kind === 'review' ? 'r' : 'q'}/${encodeURIComponent(id)}`;
+        return linkBase(notifyConfig(), this.port(), this.token, this.base) + hash;
+    }
+}
+/** Where links in notifications point: the configured base, else Tailscale (works anywhere), else the LAN. */
+export function linkBase(cfg, port, token, hubBase = '/') {
+    let base = cfg.link?.replace(/\/+$/, '');
+    if (!base) {
+        const ips = lanAddresses();
+        const ts = ips.find((ip) => /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(ip));
+        base = `http://${ts ?? ips[0] ?? os.hostname()}:${port}${hubBase.replace(/\/$/, '')}`;
+    }
+    return `${base}/${cfg.includeToken && token ? `?token=${encodeURIComponent(token)}` : ''}`;
+}
+/** Send one notice to every configured channel. */
+export async function send(cfg, n) {
+    const errors = [];
+    if (cfg.ntfy) {
+        try {
+            const u = new URL(cfg.ntfy);
+            const topic = u.pathname.replace(/^\/+|\/+$/g, '');
+            if (!topic)
+                throw new Error(`no topic in ${cfg.ntfy}`);
+            const tags = [n.approval ? 'raising_hand' : n.blocking ? 'warning' : n.kind === 'review' ? 'eyes' : n.kind === 'notes' ? 'speech_balloon' : 'question'];
+            const res = await fetch(u.origin, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...(cfg.ntfyToken ? { authorization: `Bearer ${cfg.ntfyToken}` } : {}) },
+                body: JSON.stringify({ topic, title: n.title, message: n.message, click: n.url, tags, priority: n.approval ? 5 : n.blocking ? 4 : 3 }),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!res.ok)
+                throw new Error(`ntfy: ${res.status} ${await res.text().catch(() => '')}`.trim());
+        }
+        catch (e) {
+            errors.push(e instanceof Error ? e.message : String(e));
+        }
+    }
+    if (cfg.webhook) {
+        try {
+            const res = await fetch(cfg.webhook, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(n), signal: AbortSignal.timeout(10_000) });
+            if (!res.ok)
+                throw new Error(`webhook: ${res.status}`);
+        }
+        catch (e) {
+            errors.push(e instanceof Error ? e.message : String(e));
+        }
+    }
+    if (errors.length)
+        throw new Error(errors.join('; '));
+}