@autono/pinbox-core 0.1.0

package/dist/hub-QYz6OqYQ.js

@@ -0,0 +1,328 @@
+import { AttachmentSchema, PinInputSchema, SessionRefSchema } from "./schema.js";
+import { a as NotFoundError, i as ConflictError, o as newId } from "./sessions-DrCVTMfI.js";
+import { t as POLL_OPEN_MS } from "./poll-BrcAuaAz.js";
+import { t as buildInjectionContext } from "./context-BHcEpzVb.js";
+import { z } from "zod";
+//#region src/routes-links.ts
+const LinkPostSchema = z.object({ connector: z.string() });
+const routeLinks = async (req, url, opts) => {
+	const pinId = match(url.pathname, /^\/pins\/([a-z0-9_]+)\/links$/);
+	if (pinId === null) return null;
+	const { store } = opts;
+	if (req.method === "GET") {
+		mustGetPin(store, pinId);
+		return ok(200, store.links.forPin(pinId));
+	}
+	if (req.method !== "POST") return null;
+	const pin = mustGetPin(store, pinId);
+	const body = LinkPostSchema.parse(await readJson(req));
+	const connector = opts.connectors?.find((c) => c.name === body.connector);
+	if (connector === void 0) return err(502, "E_CONNECTOR", `no connector available: ${body.connector}`, { hint: "run `pinbox doctor` to see which connectors this hub can reach" });
+	let link;
+	try {
+		link = await connector.createItem(pin, store.getThread(pinId));
+	} catch (cause) {
+		const message = cause instanceof Error ? cause.message : "connector request failed";
+		const hint = cause instanceof Error && "hint" in cause && typeof cause.hint === "string" ? cause.hint : void 0;
+		return err(502, "E_CONNECTOR", message, hint === void 0 ? void 0 : { hint });
+	}
+	const updated = store.addLink(pinId, link);
+	store.setDueAt(pinId, new Date(Date.now() + POLL_OPEN_MS).toISOString());
+	return ok(201, updated);
+};
+//#endregion
+//#region src/routes-sessions.ts
+async function routeSessions(req, url, opts) {
+	const { store } = opts;
+	const { sessions } = store;
+	if (url.pathname === "/sessions") {
+		if (req.method === "POST") {
+			const ref = SessionRefSchema.parse(await readJson(req));
+			return ok(sessions.findByRef(ref) === null ? 201 : 200, sessions.register(ref));
+		}
+		if (req.method === "GET") return ok(200, sessions.list());
+		return null;
+	}
+	const injectId = match(url.pathname, /^\/sessions\/([a-z0-9_]+)\/inject$/);
+	if (injectId !== null && req.method === "POST") return inject(store, injectId);
+	const pendingId = match(url.pathname, /^\/sessions\/([a-z0-9_]+)\/pending$/);
+	if (pendingId !== null && req.method === "GET") return pending(store, pendingId);
+	const sessionId = match(url.pathname, /^\/sessions\/([a-z0-9_]+)$/);
+	if (sessionId !== null && req.method === "DELETE") {
+		sessions.end(sessionId);
+		return ok(200, mustGetSession(sessions, sessionId));
+	}
+	return null;
+}
+/**
+* The hook pull: touch the session, flip its pending delivery rows to delivered, and
+* ALSO claim unassigned pending rows (assign → deliver — rule 1's "the next session to
+* register receives all unassigned pins", satisfied at first pull). The context always
+* carries ALL open pins: re-injection every turn is the delivery model that made
+* attachments path-only.
+*/
+function inject(store, id) {
+	const session = mustGetSession(store.sessions, id);
+	const { deliveries } = store;
+	store.sessions.touch(session.id);
+	let delivered = 0;
+	for (const row of deliveries.pendingForSession(session.id)) {
+		deliveries.markDelivered(row.id);
+		delivered += 1;
+	}
+	for (const row of deliveries.unassigned()) {
+		deliveries.assign(row.id, session.id);
+		deliveries.markDelivered(row.id);
+		delivered += 1;
+	}
+	const pins = store.listPins({ status: "open" });
+	return ok(200, {
+		context: buildInjectionContext(pins),
+		pins,
+		delivered
+	});
+}
+/**
+* Read-only Stop-hook gate: the OPEN pins referenced by this session's pending
+* delivery rows. Rows whose pin has since been resolved do not hold the agent —
+* `count` is the count of actionable pins, not of ledger rows.
+*/
+function pending(store, id) {
+	const session = mustGetSession(store.sessions, id);
+	const pins = openPinsFor(store, store.deliveries.pendingForSession(session.id));
+	return ok(200, {
+		count: pins.length,
+		pins
+	});
+}
+function openPinsFor(store, rows) {
+	const seen = /* @__PURE__ */ new Set();
+	const pins = [];
+	for (const row of rows) {
+		const event = store.eventsAfter(row.eventSeq - 1)[0];
+		if (event === void 0 || event.seq !== row.eventSeq) continue;
+		const pinId = pinIdOf(event.payload);
+		if (pinId === null || seen.has(pinId)) continue;
+		seen.add(pinId);
+		const pin = store.getPin(pinId);
+		if (pin?.status === "open") pins.push(pin);
+	}
+	return pins;
+}
+/** pin.created payloads are the Pin (`id`); thread.message payloads carry `pinId`. */
+function pinIdOf(payload) {
+	if (typeof payload !== "object" || payload === null) return null;
+	const record = payload;
+	const id = "pinId" in record ? record["pinId"] : record["id"];
+	return typeof id === "string" && id.startsWith("pin_") ? id : null;
+}
+function mustGetSession(sessions, id) {
+	const session = sessions.get(id);
+	if (!session) throw new NotFoundError(`session not found: ${id}`);
+	return session;
+}
+//#endregion
+//#region src/attachments.ts
+const MAX_ATTACHMENT_BYTES = 5242880;
+const sinks = /* @__PURE__ */ new WeakMap();
+function registerAttachmentSink(store, sink) {
+	sinks.set(store, sink);
+}
+function attachmentSinkFor(store) {
+	return sinks.get(store);
+}
+//#endregion
+//#region src/routes-toolbar.ts
+const VerifyPostSchema = z.object({ outcome: z.enum(["accepted", "reopened"]) });
+const AttachmentKindSchema = z.enum(["screenshot", "file"]);
+const routeToolbar = async (req, url, opts) => {
+	const verifyPinId = match(url.pathname, /^\/pins\/([a-z0-9_]+)\/verify$/);
+	if (verifyPinId !== null && req.method === "POST") {
+		const body = VerifyPostSchema.parse(await readJson(req));
+		return ok(200, opts.store.verifyPin(verifyPinId, body.outcome));
+	}
+	if (url.pathname === "/attachments" && req.method === "POST") return postAttachment(req, url, opts);
+	return null;
+};
+async function postAttachment(req, url, opts) {
+	const kind = AttachmentKindSchema.parse(url.searchParams.get("kind"));
+	const contentType = req.headers.get("content-type");
+	if (contentType === null || contentType === "") return err(400, "E_INVALID_INPUT", "content-type header is required", { hint: "send the attachment's MIME type, e.g. content-type: image/webp" });
+	const tooLarge = () => err(413, "E_ATTACHMENT", `attachment exceeds ${MAX_ATTACHMENT_BYTES} bytes`, { hint: "attachments are capped at 5 MB; downscale or compress before uploading" });
+	const declared = Number(req.headers.get("content-length"));
+	if (Number.isFinite(declared) && declared > 5242880) return tooLarge();
+	const bytes = new Uint8Array(await req.arrayBuffer());
+	if (bytes.byteLength > 5242880) return tooLarge();
+	const sink = attachmentSinkFor(opts.store);
+	if (sink === void 0) return err(500, "E_INTERNAL", "no attachment sink registered for this store", { hint: "the host must call registerAttachmentSink(store, sink) before serving /attachments" });
+	const { attachment, uploadUrl } = await sink.write({
+		id: newId("att"),
+		kind,
+		contentType
+	}, bytes);
+	return ok(201, uploadUrl === void 0 ? { attachment } : {
+		attachment,
+		uploadUrl
+	});
+}
+//#endregion
+//#region src/hub.ts
+const HUB_VERSION = "0.1.0";
+const StatusFilterSchema = z.enum(["open", "resolved"]);
+const AfterSchema = z.coerce.number().int().nonnegative();
+const ThreadPostSchema = z.object({
+	role: z.enum([
+		"human",
+		"agent",
+		"mirror"
+	]),
+	text: z.string().min(1),
+	attachments: z.array(AttachmentSchema).optional(),
+	origin: z.string().optional()
+});
+const ResolvePostSchema = z.object({
+	by: z.enum(["human", "agent"]),
+	note: z.string().optional(),
+	commit: z.string().optional()
+});
+const ROUTES = [
+	routeCollections,
+	routePinItem,
+	routeSessions,
+	routeToolbar,
+	routeLinks
+];
+function createHubHandler(opts) {
+	return async (req) => {
+		const url = new URL(req.url);
+		if (req.method === "GET" && url.pathname === "/health") return ok(200, {
+			version: HUB_VERSION,
+			schemaVersion: 1,
+			wsProtocol: 1
+		});
+		if (opts.verify) {
+			if (await opts.verify(req) === null) return err(401, "E_AUTH", "request rejected by the configured verifier", { hint: "send a credential the hub's verify strategy accepts" });
+		} else if (req.headers.get("authorization") !== `Bearer ${opts.token}`) return err(401, "E_INVALID_INPUT", "missing or invalid bearer token", { hint: "send Authorization: Bearer <token>; the token lives in the XDG state file" });
+		try {
+			return await route(req, url, opts);
+		} catch (cause) {
+			return mapError(cause);
+		}
+	};
+}
+async function route(req, url, opts) {
+	for (const routeModule of ROUTES) {
+		const response = await routeModule(req, url, opts);
+		if (response) return response;
+	}
+	throw new NotFoundError(`no route: ${req.method} ${url.pathname}`);
+}
+async function routeCollections(req, url, opts) {
+	const { store } = opts;
+	switch (`${req.method} ${url.pathname}`) {
+		case "GET /summary": {
+			const sessions = store.sessions.list().filter((s) => s.endedAt === void 0).length;
+			return ok(200, {
+				...store.summary(),
+				sessions
+			});
+		}
+		case "GET /events": {
+			const after = url.searchParams.get("after");
+			return ok(200, store.eventsAfter(after === null ? 0 : AfterSchema.parse(after)));
+		}
+		case "POST /pins": {
+			const input = PinInputSchema.parse(await readJson(req));
+			return ok(201, store.createPin(input, opts.enrichEnv?.() ?? {}));
+		}
+		case "GET /pins": {
+			const search = url.searchParams.get("search");
+			if (search !== null) return ok(200, store.searchPins(search));
+			const status = url.searchParams.get("status");
+			const filter = status === null ? void 0 : { status: StatusFilterSchema.parse(status) };
+			return ok(200, store.listPins(filter));
+		}
+		default: return null;
+	}
+}
+async function routePinItem(req, url, opts) {
+	const { store } = opts;
+	const { method } = req;
+	const path = url.pathname;
+	const pinId = match(path, /^\/pins\/([a-z0-9_]+)$/);
+	if (pinId !== null && method === "GET") return ok(200, mustGetPin(store, pinId));
+	const threadPinId = match(path, /^\/pins\/([a-z0-9_]+)\/thread$/);
+	if (threadPinId !== null && method === "GET") {
+		mustGetPin(store, threadPinId);
+		return ok(200, store.getThread(threadPinId));
+	}
+	if (threadPinId !== null && method === "POST") {
+		const body = ThreadPostSchema.parse(await readJson(req));
+		const messageOpts = {
+			...body.attachments === void 0 ? {} : { attachments: body.attachments },
+			...body.origin === void 0 ? {} : { origin: body.origin }
+		};
+		const hasOpts = Object.keys(messageOpts).length > 0;
+		return ok(201, store.addThreadMessage(threadPinId, body.role, body.text, hasOpts ? messageOpts : void 0));
+	}
+	const resolvePinId = match(path, /^\/pins\/([a-z0-9_]+)\/resolve$/);
+	if (resolvePinId !== null && method === "POST") {
+		const body = ResolvePostSchema.parse(await readJson(req));
+		return ok(200, store.resolvePin(resolvePinId, body.by, body.note, body.commit));
+	}
+	return null;
+}
+function match(path, pattern) {
+	return pattern.exec(path)?.[1] ?? null;
+}
+function mustGetPin(store, id) {
+	const pin = store.getPin(id);
+	if (!pin) throw new NotFoundError(`pin not found: ${id}`);
+	return pin;
+}
+async function readJson(req) {
+	try {
+		return await req.json();
+	} catch {
+		throw new BodyNotJsonError();
+	}
+}
+var BodyNotJsonError = class extends Error {};
+function json(status, body) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" }
+	});
+}
+function ok(status, data) {
+	return json(status, {
+		ok: true,
+		data
+	});
+}
+function err(status, code, message, extra) {
+	const hint = extra?.hint;
+	return json(status, {
+		ok: false,
+		error: hint === void 0 ? {
+			code,
+			message
+		} : {
+			code,
+			message,
+			hint
+		}
+	});
+}
+function mapError(cause) {
+	if (cause instanceof NotFoundError) return err(404, "E_NOT_FOUND", cause.message);
+	if (cause instanceof ConflictError) return err(409, "E_CONFLICT", cause.message);
+	if (cause instanceof z.ZodError) {
+		const issue = cause.issues[0];
+		return err(400, "E_INVALID_INPUT", issue ? `${issue.path.length > 0 ? `${issue.path.join(".")}: ` : ""}${issue.message}` : "invalid input");
+	}
+	if (cause instanceof BodyNotJsonError) return err(400, "E_INVALID_INPUT", "request body is not valid JSON", { hint: "send a JSON body with content-type: application/json" });
+	return err(500, "E_INTERNAL", cause instanceof Error ? cause.message : "unexpected error");
+}
+//#endregion
+export { mustGetPin as a, registerAttachmentSink as c, match as i, createHubHandler as n, ok as o, err as r, readJson as s, BodyNotJsonError as t };

package/dist/hub-server.d.ts

@@ -0,0 +1,44 @@
+import { t as Attachment } from "./schema-BOTmn5SM.js";
+import { c as PinStore } from "./store-DHbwWu93.js";
+import { HubOptions } from "./hub.js";
+//#region src/attachments.d.ts
+interface AttachmentSink {
+  /** Persist bytes; return the finished Attachment (local: path set; cloud R2: url + uploadUrl). */
+  write(meta: {
+    id: string;
+    kind: "screenshot" | "file";
+    contentType: string;
+  }, bytes: Uint8Array): Promise<{
+    attachment: Attachment;
+    uploadUrl?: string;
+  }>;
+}
+declare function registerAttachmentSink(store: PinStore, sink: AttachmentSink): void;
+//#endregion
+//#region src/attachments-local.d.ts
+/** Bytes to `${dir}/${id}.${ext}`; Bun.write creates the directory tree on demand. */
+declare function localDirSink(dir: string): AttachmentSink;
+//#endregion
+//#region src/git-env.d.ts
+declare function gitEnv(cwd: string): {
+  branch?: string;
+  commit?: string;
+};
+//#endregion
+//#region src/hub-server.d.ts
+type RealtimeOptions = {
+  projectId: string;
+  /** Test override for the 5s hello deadline. */
+  helloTimeoutMs?: number;
+};
+declare function startHubServer(opts: HubOptions & {
+  port?: number;
+  idleMs?: number;
+  realtime?: RealtimeOptions;
+}): Promise<{
+  port: number;
+  url: string;
+  close: () => Promise<void>;
+}>;
+//#endregion
+export { RealtimeOptions, gitEnv, localDirSink, registerAttachmentSink, startHubServer };

package/dist/hub-server.js

@@ -0,0 +1,251 @@
+import { c as registerAttachmentSink, n as createHubHandler } from "./hub-QYz6OqYQ.js";
+import { ClientHelloSchema, WS_CLOSE_PROTOCOL, WS_CLOSE_UNAUTHORIZED, WS_TOKEN_SUBPROTOCOL_PREFIX, encodeWsEvent } from "./ws-protocol.js";
+//#region src/attachments-local.ts
+const EXTENSIONS = {
+	"image/png": "png",
+	"image/webp": "webp",
+	"image/jpeg": "jpg",
+	"image/gif": "gif",
+	"text/plain": "txt"
+};
+function extensionFor(contentType) {
+	const essence = (contentType.split(";")[0] ?? "").trim().toLowerCase();
+	return EXTENSIONS[essence] ?? "bin";
+}
+/** Bytes to `${dir}/${id}.${ext}`; Bun.write creates the directory tree on demand. */
+function localDirSink(dir) {
+	return { async write(meta, bytes) {
+		const path = `${dir}/${meta.id}.${extensionFor(meta.contentType)}`;
+		await Bun.write(path, bytes);
+		return { attachment: {
+			id: meta.id,
+			kind: meta.kind,
+			path,
+			contentType: meta.contentType
+		} };
+	} };
+}
+//#endregion
+//#region src/git-env.ts
+function gitEnv(cwd) {
+	const branch = revParse(cwd, "--abbrev-ref", "HEAD");
+	const commit = revParse(cwd, "HEAD");
+	if (branch === null || commit === null) return {};
+	return {
+		branch,
+		commit
+	};
+}
+function revParse(cwd, ...args) {
+	try {
+		const result = Bun.spawnSync([
+			"git",
+			"rev-parse",
+			...args
+		], { cwd });
+		if (!result.success) return null;
+		const out = result.stdout.toString().trim();
+		return out === "" ? null : out;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/hub-server.ts
+const DEFAULT_IDLE_MS = 18e5;
+const DEFAULT_HELLO_TIMEOUT_MS = 5e3;
+const BACKPRESSURE_LIMIT_BYTES = 1048576;
+function startHubServer(opts) {
+	const handler = createHubHandler(opts);
+	const idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
+	const { realtime } = opts;
+	const topic = `project:${realtime?.projectId ?? ""}`;
+	const sockets = { count: 0 };
+	let idleTimer;
+	const touchIdleTimer = () => {
+		clearTimeout(idleTimer);
+		idleTimer = setTimeout(() => {
+			if (sockets.count > 0) {
+				touchIdleTimer();
+				return;
+			}
+			close();
+		}, idleMs);
+		idleTimer.unref();
+	};
+	const server = Bun.serve({
+		hostname: "127.0.0.1",
+		port: opts.port ?? 0,
+		fetch: (req, srv) => {
+			touchIdleTimer();
+			if (!realtime) return handler(req);
+			return realtimeFetch(req, srv, handler, opts.token, topic);
+		},
+		websocket: wsHandlers(opts.store, topic, realtime?.helloTimeoutMs ?? DEFAULT_HELLO_TIMEOUT_MS, sockets)
+	});
+	const broadcaster = {
+		publish: (t, d) => void server.publish(t, d),
+		subscriberCount: (t) => server.subscriberCount(t)
+	};
+	const unsubscribe = realtime ? opts.store.subscribe((event) => broadcaster.publish(topic, encodeWsEvent(event))) : void 0;
+	const close = async () => {
+		clearTimeout(idleTimer);
+		unsubscribe?.();
+		await Promise.race([server.stop(true), Bun.sleep(50)]);
+	};
+	const { port } = server;
+	if (port === void 0) throw new Error("hub server bound without a TCP port");
+	touchIdleTimer();
+	return Promise.resolve({
+		port,
+		url: server.url.href,
+		close
+	});
+}
+async function realtimeFetch(req, server, handler, token, topic) {
+	const url = new URL(req.url);
+	if (url.pathname === "/ws") return upgradeWs(req, url, server, token);
+	const origin = req.headers.get("origin");
+	const gated = corsGate(req, origin);
+	if (gated !== null) return gated;
+	let res = await handler(req);
+	if (req.method === "GET" && url.pathname === "/summary" && res.status === 200) res = await withConnectedToolbars(res, server.subscriberCount(topic));
+	return origin === null ? res : withAllowOrigin(res, origin);
+}
+function corsGate(req, origin) {
+	if (origin === null) return null;
+	if (!isLoopbackOrigin(origin)) return new Response(null, { status: 403 });
+	if (req.method === "OPTIONS") return preflight(origin);
+	return null;
+}
+function upgradeWs(req, url, server, token) {
+	const entry = (req.headers.get("sec-websocket-protocol") ?? "").split(",").map((part) => part.trim()).find((part) => part.startsWith(WS_TOKEN_SUBPROTOCOL_PREFIX));
+	const data = {
+		authorized: (entry?.slice(13) ?? url.searchParams.get("token")) === token,
+		helloDone: false,
+		helloTimer: void 0
+	};
+	server.timeout(req, 0);
+	return server.upgrade(req, {
+		data,
+		...entry === void 0 ? {} : { headers: { "sec-websocket-protocol": entry } }
+	}) ? void 0 : new Response("websocket upgrade failed", { status: 400 });
+}
+function wsHandlers(store, topic, helloTimeoutMs, sockets) {
+	return {
+		sendPings: true,
+		backpressureLimit: BACKPRESSURE_LIMIT_BYTES,
+		closeOnBackpressureLimit: true,
+		open(ws) {
+			sockets.count += 1;
+			if (!ws.data.authorized) {
+				ws.close(WS_CLOSE_UNAUTHORIZED, "missing or invalid token");
+				return;
+			}
+			ws.subscribe(topic);
+			ws.data.helloTimer = setTimeout(() => {
+				ws.close(WS_CLOSE_PROTOCOL, "no hello within deadline");
+			}, helloTimeoutMs);
+		},
+		message(ws, raw) {
+			onWsMessage(store, ws, raw);
+		},
+		close(ws) {
+			sockets.count -= 1;
+			clearTimeout(ws.data.helloTimer);
+		}
+	};
+}
+function onWsMessage(store, ws, raw) {
+	if (ws.data.helloDone) {
+		ws.send(errorFrame("unexpected client frame: no client messages exist after hello"));
+		return;
+	}
+	const hello = parseHello(raw);
+	if (hello === null) {
+		ws.send(errorFrame("malformed hello"));
+		ws.close(WS_CLOSE_PROTOCOL, "malformed hello");
+		return;
+	}
+	if (hello.protocol < 1) {
+		ws.send(errorFrame(`protocol ${hello.protocol} below minimum 1`));
+		ws.close(WS_CLOSE_PROTOCOL, "protocol below minimum");
+		return;
+	}
+	clearTimeout(ws.data.helloTimer);
+	ws.data.helloDone = true;
+	const events = store.eventsAfter(hello.lastSeq).map((event) => ({
+		type: "event",
+		seq: event.seq,
+		eventType: event.type,
+		at: event.at,
+		payload: event.payload
+	}));
+	ws.send(JSON.stringify({
+		type: "catch-up",
+		protocol: 1,
+		minProtocol: 1,
+		lastSeq: store.summary().lastEventSeq,
+		events
+	}));
+	store.cursors.set(hello.consumerId, hello.lastSeq);
+}
+function parseHello(raw) {
+	try {
+		const parsed = ClientHelloSchema.safeParse(JSON.parse(String(raw)));
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+function errorFrame(message) {
+	return JSON.stringify({
+		type: "error",
+		code: "E_WS_PROTOCOL",
+		message
+	});
+}
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]",
+	"::1"
+]);
+function isLoopbackOrigin(origin) {
+	try {
+		return LOOPBACK_HOSTS.has(new URL(origin).hostname);
+	} catch {
+		return false;
+	}
+}
+function preflight(origin) {
+	return new Response(null, {
+		status: 204,
+		headers: {
+			"access-control-allow-origin": origin,
+			"access-control-allow-methods": "GET, POST, OPTIONS",
+			"access-control-allow-headers": "authorization, content-type",
+			"access-control-max-age": "600",
+			vary: "origin"
+		}
+	});
+}
+function withAllowOrigin(res, origin) {
+	const headers = new Headers(res.headers);
+	headers.set("access-control-allow-origin", origin);
+	headers.set("vary", "origin");
+	return new Response(res.body, {
+		status: res.status,
+		headers
+	});
+}
+async function withConnectedToolbars(res, connectedToolbars) {
+	const body = await res.json();
+	body.data["connectedToolbars"] = connectedToolbars;
+	return new Response(JSON.stringify(body), {
+		status: res.status,
+		headers: { "content-type": "application/json" }
+	});
+}
+//#endregion
+export { gitEnv, localDirSink, registerAttachmentSink, startHubServer };