harnery 0.26.0 → 0.28.0

package/src/core/workflow/workspaces/state.ts

@@ -17,6 +17,9 @@ import {
   stableDigest,
   writeImmutableJson,
 } from "../durable-record.ts";
+
+export { appendWorkflowJournalEvent } from "../journal.ts";
+
 import type {
   GitRepositoryBinding,
   IntegrationApplyAttempt,
@@ -34,7 +37,7 @@ import type {
 } from "./types.ts";
 
 const JSON_LIMIT = 512 * 1024;
-const EVENT_LIMIT = 32 * 1024;
+const WORKSPACE_EVENT_BYTES = 32 * 1024;
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
 
 export interface WorkspaceClaim {
@@ -181,7 +184,11 @@ export function appendWorkspaceEvent(
   event: string,
   data: Record<string, unknown> = {},
 ): WorkspaceProviderEvent {
-  if (!event || event.length > 100 || Buffer.byteLength(JSON.stringify(data)) > EVENT_LIMIT / 2) {
+  if (
+    !event ||
+    event.length > 100 ||
+    Buffer.byteLength(JSON.stringify(data)) > WORKSPACE_EVENT_BYTES / 2
+  ) {
     throw new Error("workspace provider event is invalid or too large");
   }
   const path = workspaceEventsPath(coordRoot, claim.provider_id, claim.binding_id);
@@ -204,7 +211,7 @@ export function appendWorkspaceEvent(
     record_sha256: stableDigest(basis),
   };
   const line = `${canonicalJson(record)}\n`;
-  if (Buffer.byteLength(line) > EVENT_LIMIT)
+  if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES)
     throw new Error("workspace provider event is too large");
   const fd = openSync(path, "a", 0o600);
   try {
@@ -232,7 +239,7 @@ export function readWorkspaceEvents(
     .split("\n")
     .filter(Boolean)
     .map((line, index) => {
-      if (Buffer.byteLength(line) > EVENT_LIMIT) {
+      if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES) {
         throw new Error(`workspace event ${index + 1} is too large`);
       }
       let record: WorkspaceProviderEvent;
@@ -270,33 +277,6 @@ function recordsDigestPlaceholder(): null {
   return null;
 }
 
-export function appendWorkflowJournalEvent(
-  coordRoot: string,
-  runId: string,
-  event: string,
-  data: Record<string, unknown>,
-): void {
-  const path = join(workflowRunDir(coordRoot, runId), "journal.jsonl");
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const existed = existsSync(path);
-  const line = `${JSON.stringify({
-    schema_version: 1,
-    run_id: runId,
-    ts: new Date().toISOString(),
-    event,
-    ...data,
-  })}\n`;
-  if (Buffer.byteLength(line) > EVENT_LIMIT) throw new Error("workflow journal event is too large");
-  const fd = openSync(path, "a", 0o600);
-  try {
-    writeFileSync(fd, line, "utf8");
-    fsyncSync(fd);
-  } finally {
-    closeSync(fd);
-  }
-  if (!existed) fsyncParentDirectory(path);
-}
-
 export type WorkflowSupplement =
   | WorkspaceBinding
   | IntegrationReviewRecord
@@ -327,7 +307,7 @@ export function appendCleanupAttempt(
     record_sha256: stableDigest(basis),
   };
   const line = `${canonicalJson(attempt)}\n`;
-  if (Buffer.byteLength(line) > EVENT_LIMIT) {
+  if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES) {
     throw new Error("workspace cleanup attempt is too large");
   }
   const fd = openSync(path, "a", 0o600);
@@ -388,7 +368,7 @@ function appendChainedRecord(
   label: string,
 ): void {
   const line = `${canonicalJson(record)}\n`;
-  if (Buffer.byteLength(line) > EVENT_LIMIT) {
+  if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES) {
     throw new Error(`${label} is too large`);
   }
   const fd = openSync(path, "a", 0o600);

package/src/lib/browser/client.ts

@@ -295,6 +295,135 @@ export class Browser {
     return buf.length;
   }
 
+  /**
+   * Capture a full-page screenshot from an explicit capture viewport and
+   * evaluate the caller's final evidence expression immediately before the
+   * pixels are written. Playwright normally manages the full-page viewport
+   * internally, which leaves callers unable to inspect fixed/sticky geometry
+   * in the state the PNG actually renders.
+   */
+  async screenshotWithEvaluation<T = unknown>(
+    path: string,
+    evaluation: string,
+    opts: { fullPage?: boolean } = {},
+  ): Promise<{
+    bytes: number;
+    evaluation: T;
+    viewport: { width: number; height: number };
+    evidence: {
+      converged: boolean;
+      reason: string;
+      passes: number;
+      max_passes: number;
+      max_dimension: number;
+      max_pixels: number;
+      original_viewport: { width: number; height: number };
+      evaluated_viewport: { width: number; height: number };
+      document_extent_before_evaluation: { width: number; height: number };
+      document_extent_after_evaluation: { width: number; height: number };
+      document_extent_after_screenshot: { width: number; height: number };
+      screenshot: { width: number; height: number; bytes: number };
+    };
+  }> {
+    const page = this.currentPage;
+    const fullPage = opts.fullPage ?? true;
+    const maxPasses = 4;
+    const maxDimension = 32_000;
+    const maxPixels = 128_000_000;
+    const documentExtent = () =>
+      page.evaluate(() => ({
+        width: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0),
+        height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0),
+      }));
+    const originalViewport = page.viewportSize();
+    if (!originalViewport) {
+      throw new Error("Capture-state evaluation requires a page with an explicit viewport.");
+    }
+    let captureViewport = originalViewport;
+    let passes = fullPage ? 0 : 1;
+    let extentBeforeEvaluation = await documentExtent();
+    let bounded = true;
+    if (fullPage) {
+      for (let pass = 0; pass < maxPasses; pass += 1) {
+        passes = pass + 1;
+        const nextViewport = {
+          width: originalViewport.width,
+          height: Math.max(originalViewport.height, Math.ceil(extentBeforeEvaluation.height)),
+        };
+        bounded =
+          nextViewport.width <= maxDimension &&
+          nextViewport.height <= maxDimension &&
+          nextViewport.width * nextViewport.height <= maxPixels;
+        if (!bounded) break;
+        if (
+          nextViewport.width === captureViewport.width &&
+          nextViewport.height === captureViewport.height &&
+          extentBeforeEvaluation.width <= captureViewport.width &&
+          extentBeforeEvaluation.height === captureViewport.height
+        ) {
+          break;
+        }
+        captureViewport = nextViewport;
+        await page.setViewportSize(captureViewport);
+        extentBeforeEvaluation = await documentExtent();
+      }
+    }
+    try {
+      const evaluationResult = await page.evaluate<T>(evaluation);
+      const extentAfterEvaluation = await documentExtent();
+      const buf = await page.screenshot({ path, fullPage: fullPage && bounded, type: "png" });
+      const extentAfterScreenshot = await documentExtent();
+      const screenshot = {
+        width: buf.readUInt32BE(16),
+        height: buf.readUInt32BE(20),
+        bytes: buf.length,
+      };
+      const exact = fullPage
+        ? bounded &&
+          captureViewport.width === extentBeforeEvaluation.width &&
+          captureViewport.height === extentBeforeEvaluation.height &&
+          captureViewport.width === extentAfterEvaluation.width &&
+          captureViewport.height === extentAfterEvaluation.height &&
+          captureViewport.width === extentAfterScreenshot.width &&
+          captureViewport.height === extentAfterScreenshot.height &&
+          captureViewport.width === screenshot.width &&
+          captureViewport.height === screenshot.height
+        : captureViewport.width === screenshot.width &&
+          captureViewport.height === screenshot.height;
+      const reason = !bounded
+        ? "capture_bounds_exceeded"
+        : exact
+          ? "capture_viewport_converged"
+          : "capture_viewport_non_convergent";
+      return {
+        bytes: buf.length,
+        evaluation: evaluationResult,
+        viewport: captureViewport,
+        evidence: {
+          converged: exact,
+          reason,
+          passes,
+          max_passes: maxPasses,
+          max_dimension: maxDimension,
+          max_pixels: maxPixels,
+          original_viewport: originalViewport,
+          evaluated_viewport: captureViewport,
+          document_extent_before_evaluation: extentBeforeEvaluation,
+          document_extent_after_evaluation: extentAfterEvaluation,
+          document_extent_after_screenshot: extentAfterScreenshot,
+          screenshot,
+        },
+      };
+    } finally {
+      if (
+        captureViewport.width !== originalViewport.width ||
+        captureViewport.height !== originalViewport.height
+      ) {
+        await page.setViewportSize(originalViewport);
+      }
+    }
+  }
+
   /**
    * Plain-text snapshot of the document body. Suitable as a coarse "what's
    * on screen" signal for LLM iteration loops. For richer extraction, use

package/src/lib/exec.ts

@@ -13,6 +13,10 @@ export interface ExecResult {
   stdout: string;
   stderr: string;
   exitCode: number;
+  /** True when this process killed the child for exceeding `opts.timeout`. A
+   * child that handles the signal cleanly still exits 0, so the exit code alone
+   * cannot distinguish a kill from an ordinary finish. */
+  timedOut?: boolean;
 }
 
 export interface ExecOpts {
@@ -46,7 +50,11 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
     proc.stderr?.on("data", (d: Buffer) => err.push(d));
 
     const timeout = opts.timeout ?? 30_000;
-    const timer = setTimeout(() => proc.kill(), timeout);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill();
+    }, timeout);
 
     const finish = (exitCode: number, errOverride?: string): void => {
       clearTimeout(timer);
@@ -57,6 +65,7 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
         stdout: shouldTrim ? stdout.trim() : stdout.replace(/\n$/, ""),
         stderr: shouldTrim ? stderr.trim() : stderr.replace(/\n$/, ""),
         exitCode,
+        ...(timedOut ? { timedOut: true } : {}),
       });
     };
 

package/src/lib/tunnel/error-page.ts

@@ -0,0 +1,114 @@
+export interface TunnelErrorPageOptions {
+  kind: "access-denied" | "upstream-unavailable";
+  incidentId: string;
+  timestamp: string;
+  tunnelName: string;
+  method: string;
+  path: string;
+  clientIp: string;
+  cloudflareRay: string;
+  target?: string;
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}
+
+function diagnosticText(options: TunnelErrorPageOptions): string {
+  const lines = [
+    `Tunnel incident: ${options.incidentId}`,
+    `Time: ${options.timestamp}`,
+    `Problem: ${options.kind}`,
+    `Tunnel: ${options.tunnelName}`,
+    `Request: ${options.method} ${options.path}`,
+    `Client IP: ${options.clientIp || "(not provided by proxy)"}`,
+    `Cloudflare Ray: ${options.cloudflareRay || "(not provided)"}`,
+  ];
+
+  if (options.target) lines.push(`Upstream: ${options.target}`);
+  if (options.errorCode) lines.push(`Error code: ${options.errorCode}`);
+  if (options.errorMessage) lines.push(`Error: ${options.errorMessage}`);
+
+  return lines.join("\n");
+}
+
+export function renderTunnelErrorPage(options: TunnelErrorPageOptions): string {
+  const denied = options.kind === "access-denied";
+  const title = denied ? "This device is not allowed yet" : "The preview is temporarily offline";
+  const summary = denied
+    ? "The tunnel is running, but this device's public IP is not on its access list."
+    : "The public tunnel and access check are working, but the local preview server is not responding.";
+  const nextStep = denied
+    ? "Copy the diagnostic below and send it to the person running the tunnel. It includes the public IP that needs to be allowed."
+    : "Copy the diagnostic below and send it to the person running the tunnel. The incident ID can be matched to the server log.";
+  const diagnostic = diagnosticText(options);
+  const safeDiagnosticForScript = JSON.stringify(diagnostic).replaceAll("<", "\\u003c");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="robots" content="noindex,nofollow">
+  <title>${escapeHtml(title)}</title>
+  <style>
+    :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    * { box-sizing: border-box; }
+    body { margin: 0; min-height: 100vh; background: #f4f2ed; color: #17211c; display: grid; place-items: center; padding: 24px; }
+    main { width: min(100%, 720px); background: #fff; border: 1px solid #d8d4ca; border-radius: 18px; box-shadow: 0 18px 50px rgba(23, 33, 28, .10); overflow: hidden; }
+    .bar { height: 8px; background: ${denied ? "#b54708" : "#b42318"}; }
+    .content { padding: clamp(24px, 5vw, 48px); }
+    .eyebrow { margin: 0 0 10px; color: ${denied ? "#8a3708" : "#912018"}; font-size: 13px; font-weight: 750; letter-spacing: .09em; text-transform: uppercase; }
+    h1 { margin: 0; max-width: 18ch; font-size: clamp(30px, 7vw, 48px); line-height: 1.02; letter-spacing: -.04em; }
+    .summary { margin: 20px 0 10px; max-width: 58ch; font-size: 18px; line-height: 1.55; }
+    .next { margin: 0 0 24px; max-width: 62ch; color: #536058; line-height: 1.55; }
+    .diagnostic-wrap { position: relative; }
+    pre { margin: 0; padding: 18px; border: 1px solid #ccd2cd; border-radius: 12px; background: #111814; color: #edf5ef; font: 13px/1.55 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+    button { width: 100%; margin-top: 12px; border: 0; border-radius: 11px; padding: 14px 18px; background: #17643a; color: #fff; font: inherit; font-weight: 750; cursor: pointer; }
+    button:hover { background: #0e5230; }
+    button:focus-visible { outline: 3px solid #87c89f; outline-offset: 3px; }
+    .incident { margin: 18px 0 0; color: #68736c; font-size: 13px; text-align: center; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="bar"></div>
+    <div class="content">
+      <p class="eyebrow">Tunnel diagnostic</p>
+      <h1>${escapeHtml(title)}</h1>
+      <p class="summary">${escapeHtml(summary)}</p>
+      <p class="next">${escapeHtml(nextStep)}</p>
+      <div class="diagnostic-wrap">
+        <pre id="diagnostic">${escapeHtml(diagnostic)}</pre>
+        <button id="copy" type="button">Copy diagnostic</button>
+      </div>
+      <p class="incident">Incident ${escapeHtml(options.incidentId)}</p>
+    </div>
+  </main>
+  <script>
+    const diagnostic = ${safeDiagnosticForScript};
+    const button = document.getElementById("copy");
+    button.addEventListener("click", async () => {
+      try {
+        await navigator.clipboard.writeText(diagnostic);
+        button.textContent = "Copied";
+      } catch {
+        const range = document.createRange();
+        range.selectNodeContents(document.getElementById("diagnostic"));
+        const selection = window.getSelection();
+        selection.removeAllRanges();
+        selection.addRange(range);
+        button.textContent = "Selected — copy now";
+      }
+    });
+  </script>
+</body>
+</html>`;
+}

package/src/lib/tunnel/gate.ts

@@ -9,6 +9,8 @@
 // available; stdout/stderr is captured into .cache/tunnel/gate.log by the
 // spawner.
 
+import { renderTunnelErrorPage } from "./error-page";
+
 // `--port`/`--name` are also passed on argv (not just env) so the gate's port
 // and instance name show up in its process command line. That's what lets
 // `tunnel down` scope its stray-process sweep to a single instance via
@@ -30,6 +32,7 @@ const TARGET = process.env.HARNERY_TUNNEL_TARGET ?? "127.0.0.1:8001";
 const VHOST = process.env.HARNERY_TUNNEL_VHOST ?? "localhost";
 const PORT = Number(process.env.HARNERY_TUNNEL_PORT ?? argvFlag("--port") ?? "9001");
 const ACCESS = process.env.HARNERY_TUNNEL_ACCESS ?? "cloudflare-allowlist";
+const NAME = argvFlag("--name") ?? "default";
 
 const UPSTREAM_HTTP = `http://${TARGET}`;
 const UPSTREAM_WS = `ws://${TARGET}`;
@@ -38,6 +41,27 @@ interface WsData {
   path: string;
 }
 
+function requestDetails(req: Request, url: URL) {
+  return {
+    incidentId: crypto.randomUUID().slice(0, 8),
+    timestamp: new Date().toISOString(),
+    tunnelName: NAME,
+    method: req.method,
+    path: url.pathname + url.search,
+    clientIp: req.headers.get("cf-connecting-ip") ?? "",
+    cloudflareRay: req.headers.get("cf-ray") ?? "",
+  };
+}
+
+function errorDetails(error: unknown): { code: string; message: string } {
+  if (!(error instanceof Error)) {
+    return { code: "UnknownError", message: String(error) };
+  }
+  const code =
+    "code" in error && typeof error.code === "string" ? error.code : error.name || "Error";
+  return { code, message: error.message || "The upstream request failed." };
+}
+
 const server = Bun.serve<WsData, never>({
   port: PORT,
   hostname: "127.0.0.1",
@@ -51,13 +75,21 @@ const server = Bun.serve<WsData, never>({
     if (ACCESS === "cloudflare-allowlist") {
       const ip = req.headers.get("cf-connecting-ip") ?? "";
       if (!ALLOW.has(ip)) {
+        const details = requestDetails(req, url);
         // Log denials so operators can whitelist a phone/laptop that just
         // hit 403 without asking the human to dig up their public IP.
         console.log(
           // lint-ok-emission: detached worker, see file note above
-          `deny: ${ip || "(missing-cf-connecting-ip)"} ${req.method} ${url.pathname}`,
+          `deny: incident=${details.incidentId} ip=${ip || "(missing-cf-connecting-ip)"} ray=${details.cloudflareRay || "(missing)"} ${req.method} ${details.path}`,
         );
-        return new Response("403 Forbidden\n", { status: 403 });
+        return new Response(renderTunnelErrorPage({ ...details, kind: "access-denied" }), {
+          status: 403,
+          headers: {
+            "cache-control": "no-store",
+            "content-type": "text/html; charset=utf-8",
+            "x-harnery-tunnel-incident": details.incidentId,
+          },
+        });
       }
     }
 
@@ -81,7 +113,38 @@ const server = Bun.serve<WsData, never>({
     if (!["GET", "HEAD"].includes(req.method)) {
       init.body = await req.arrayBuffer();
     }
-    const resp = await fetch(UPSTREAM_HTTP + url.pathname + url.search, init);
+    let resp: Response;
+    try {
+      resp = await fetch(UPSTREAM_HTTP + url.pathname + url.search, init);
+    } catch (error) {
+      const details = requestDetails(req, url);
+      const failure = errorDetails(error);
+      console.log(
+        // lint-ok-emission: detached worker, see file note above
+        `upstream-error: incident=${details.incidentId} ip=${details.clientIp || "(missing-cf-connecting-ip)"} ray=${details.cloudflareRay || "(missing)"} code=${failure.code} ${req.method} ${details.path}`,
+      );
+      return new Response(
+        renderTunnelErrorPage({
+          ...details,
+          kind: "upstream-unavailable",
+          target: UPSTREAM_HTTP,
+          errorCode: failure.code,
+          errorMessage: failure.message,
+        }),
+        {
+          // Cloudflare replaces 502 response bodies with its own generic error
+          // page. Return the diagnostic as a successful document and preserve
+          // the semantic status in a header so the human can actually see it.
+          status: 200,
+          headers: {
+            "cache-control": "no-store",
+            "content-type": "text/html; charset=utf-8",
+            "x-harnery-tunnel-incident": details.incidentId,
+            "x-harnery-tunnel-status": "502",
+          },
+        },
+      );
+    }
     const respHeaders = new Headers(resp.headers);
     respHeaders.delete("content-encoding");
     respHeaders.delete("content-length");