acuvo-code 0.2.0

package/lib/parallel.mjs

@@ -0,0 +1,144 @@
+/**
+ * ── ⭐⭐ SEVERAL TASKS AT ONCE — ROMAN HAS ASKED FOR THIS FOUR TIMES ──────────
+ *
+ * *"so people can do mass work and multiple terminals, that's a good ass
+ * feature."* It is, and nobody in this category ships it well.
+ *
+ * The naive version is `for (const t of tasks) await run(t)`, which is not
+ * parallel, and the naive-parallel version is `Promise.all(tasks.map(run))`,
+ * which is parallel and dangerous. This file is the difference.
+ *
+ * ── ⚠️ THE THING THAT MAKES THIS HARD IS NOT CONCURRENCY, IT IS COLLISION ────
+ * Two agents in ONE workspace will eventually write the same file. Whoever
+ * finishes second wins, silently, and the first task reports success for work
+ * that no longer exists. ⭐ That is the failure to design around — not speed.
+ *
+ * Three honest options, and why this one:
+ *
+ *   · **Merge them.** No. Merging two model-authored versions of a file without
+ *     a human is how you get code that compiles and means nothing.
+ *   · **Lock per file.** Tempting, but a lock held across a model call is a
+ *     minute of one task blocking another, and deadlock is a real outcome once
+ *     two tasks want two files in different orders.
+ *   · **Let them run, DETECT the overlap, and refuse to pretend.** ⭐ This one.
+ *     Every task records the files it wrote; an overlap is reported loudly with
+ *     both task names, and the run is marked conflicted. Nothing is silently
+ *     lost, and the human decides.
+ *
+ * ⚠️ Sequential remains the default and always will be. Parallelism is opt-in
+ * because the safe thing must be what happens when you do not think about it.
+ */
+
+import { changedPaths } from './changed-paths.mjs';
+
+/** Sensible ceiling. Beyond this the provider rate-limits and everything slows. */
+export const MAX_CONCURRENCY = 4;
+
+/**
+ * Run tasks with bounded concurrency, preserving input order in the results.
+ *
+ * `runOne(task, index)` performs one task and resolves to its outcome.
+ *
+ * ⚠️ A REJECTION BECOMES A RESULT, NEVER AN UNHANDLED THROW. One task failing
+ * must not abandon three that are mid-flight — `Promise.all` semantics here
+ * would strand real work in a half-written state.
+ */
+export async function runPool(tasks, runOne, { concurrency = 2 } = {}) {
+  const limit = Math.max(1, Math.min(concurrency, MAX_CONCURRENCY));
+  const results = new Array(tasks.length);
+  let next = 0;
+
+  async function worker() {
+    for (;;) {
+      const i = next++;
+      if (i >= tasks.length) return;
+      try {
+        results[i] = { ok: true, index: i, task: tasks[i], outcome: await runOne(tasks[i], i) };
+      } catch (err) {
+        results[i] = { ok: false, index: i, task: tasks[i], error: err?.message ?? String(err) };
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, worker));
+  return results;
+}
+
+/**
+ * Which files did each task write, and did any two collide?
+ *
+ * ⚠️ READS `mutated`, NOT THE TOOL NAME. A future tool that also touches disk
+ * would be invisible to a name-based check — the dispatcher already sets
+ * `mutated` for exactly this reason, and trusting it keeps one source of truth.
+ */
+export function detectConflicts(results) {
+  /** @type {Map<string, string[]>} path -> task labels that wrote it */
+  const byPath = new Map();
+  for (const r of results) {
+    if (!r?.ok || !r.outcome?.executed) continue;
+    const label = shortLabel(r.task, r.index);
+    for (const rec of r.outcome.executed) {
+      /**
+       * ⭐ ONE SHARED ANSWER — see `changed-paths.mjs`. This used to be
+       * `rec.mutatedPath ?? rec.result.path` inline, which was right for the
+       * shapes that existed then and BLIND to two that exist now: a bulk
+       * `write_files` reports only its first path that way, and a `delegate`
+       * that built reports none of them. Both are file writes; a collision
+       * detector that cannot see a file write is the one thing it must not be.
+       */
+      for (const path of changedPaths(rec)) {
+        const list = byPath.get(path) ?? [];
+        if (!list.includes(label)) list.push(label);
+        byPath.set(path, list);
+      }
+    }
+  }
+  const conflicts = [...byPath.entries()]
+    .filter(([, who]) => who.length > 1)
+    .map(([path, who]) => ({ path, tasks: who }));
+  return { conflicts, filesTouched: byPath.size };
+}
+
+/** A stable, short name for a task, for use in reports. */
+export function shortLabel(task, index) {
+  const t = String(task ?? '').trim().replace(/\s+/g, ' ');
+  return `#${index + 1} ${t.length > 42 ? `${t.slice(0, 39)}…` : t}`;
+}
+
+/**
+ * Render the whole run.
+ *
+ * ⭐ CONFLICTS ARE THE HEADLINE, NOT A FOOTNOTE. If two tasks wrote the same
+ * file, that is the most important fact on the screen — more important than any
+ * of them "succeeding", because one of those successes is a lie.
+ */
+export function formatParallelSummary(results, { conflicts, filesTouched }) {
+  const lines = ['', '─'.repeat(66)];
+  const done = results.filter((r) => r?.ok && r.outcome?.ok).length;
+  const cost = results.reduce((a, r) => a + (r?.outcome?.usage?.cost ?? 0), 0);
+
+  for (const r of results) {
+    if (!r) continue;
+    const label = shortLabel(r.task, r.index);
+    if (!r.ok) { lines.push(`  ✖ ${label} — ${r.error}`); continue; }
+    const o = r.outcome;
+    const wrote = (o?.executed ?? []).filter((e) => e.mutated).length;
+    const verdict = o?.ok === false ? '✖ failed' : o?.verification?.passed ? '✔ verified' : '· done';
+    lines.push(`  ${verdict}  ${label}  ${wrote} file${wrote === 1 ? '' : 's'}`);
+  }
+
+  lines.push('', `  ${done}/${results.length} tasks · ${filesTouched} file${filesTouched === 1 ? '' : 's'} touched${cost ? ` · $${cost.toFixed(4)}` : ''}`);
+
+  if (conflicts.length > 0) {
+    lines.push('');
+    lines.push(`  ⚠ ${conflicts.length} FILE${conflicts.length === 1 ? '' : 'S'} WRITTEN BY MORE THAN ONE TASK:`);
+    for (const c of conflicts) {
+      lines.push(`     ${c.path}`);
+      lines.push(`       ${c.tasks.join('  ·  ')}`);
+    }
+    lines.push('');
+    lines.push('  ⚠ The last writer won. Whatever the other task did to that file is GONE —');
+    lines.push('    check it before trusting either result. Run them sequentially to avoid this.');
+  }
+  return lines;
+}

package/lib/perchance.mjs

@@ -0,0 +1,210 @@
+/**
+ * ── ⭐⭐ PERCHANCE, NATIVELY. NO BROWSER, NO MODAL, NO DEPENDENCY. ───────────
+ *
+ * Until today this capability needed a headless Chromium: either running on the
+ * user's machine or hosted on Modal, where it took 49s at best and returned
+ * "no finished image within 300s" at worst. Both are gone.
+ *
+ * ⚠️ AND I SAID THIS WAS IMPOSSIBLE. I tried `fetch()` once, got Cloudflare's
+ * "Just a moment...", and concluded a native path needed curl_cffi. Roman did
+ * not accept that. The measurement that followed is in `h2.mjs`: it takes
+ * HTTP/2 **and** Safari's cipher ordering, both in `node:http2`, and neither
+ * alone is enough. Three trials per cell, 200 200 200 against 403 403 403.
+ *
+ * ── THE PROTOCOL, CAPTURED FROM THE REAL CLIENT ─────────────────────────────
+ * Reverse-engineered by intercepting the generator's own requests, because the
+ * parameter shape is not documented anywhere and guessing it produced exactly
+ * one useful signal: `{"status":"invalid_parameter"}`.
+ *
+ *   1. GET  /api/verifyUser                     -> { userKey }
+ *   2. POST /api/generate?userKey&requestId…    -> { status }
+ *      ⚠️ A POST WITH A JSON BODY. My first attempt used a GET with query
+ *      params — every field in the right place, and completely wrong.
+ *   3. GET  /api/getUserQueuePosition?…         -> poll until status:"success"
+ *   4. GET  /api/downloadTemporaryImageViaProxy -> the bytes
+ *
+ * ⚠️ FRAGILE BY CONSTRUCTION, AND THAT IS STATED RATHER THAN HIDDEN. This is an
+ * undocumented private API reached through a fingerprint that a CDN may stop
+ * honouring at any time. It has no SLA and owes us nothing. Everything that uses
+ * it must keep a fallback that does not depend on it — which is why the image
+ * chain still has a second provider.
+ */
+
+import { h2Request, h2Json } from './h2.mjs';
+
+const HOST = 'https://image-generation.perchance.org';
+const CHANNEL = 'ai-text-to-image-generator';
+
+/** The generator's own cadence: it polls about once a second. */
+const POLL_INTERVAL_MS = 1_200;
+/** Total budget for one image. Beyond this an interactive loop has been abandoned. */
+const DEFAULT_BUDGET_MS = 90_000;
+
+/** Perchance uses a bare `Math.random()` string for both of these. Match it. */
+const randomId = () => String(Math.random());
+
+/**
+ * Get a userKey. No browser: the endpoint answers a plain h2 GET.
+ *
+ * ⚠️ THE KEY IS NOT A SECRET AND MUST NOT BE TREATED AS ONE — it is a
+ * rate-limiting handle the site hands to anyone who asks. It is never written to
+ * disk here, because a value that looks like a credential eventually gets
+ * committed by someone who assumed it was one.
+ */
+export async function verifyUser({ requestImpl = h2Json } = {}) {
+  const r = await requestImpl(`${HOST}/api/verifyUser`, { headers: { origin: HOST, referer: `${HOST}/` } });
+  if (!r.ok) return { ok: false, error: r.error ?? `verifyUser returned ${r.status}`, challenged: r.challenged === true };
+  const key = r.json?.userKey;
+  if (typeof key !== 'string' || key.length < 16) {
+    return { ok: false, error: `verifyUser gave no usable key: ${JSON.stringify(r.json).slice(0, 140)}` };
+  }
+  return { ok: true, userKey: key, status: r.json.status ?? null };
+}
+
+/** Ask for an image. Returns the requestId the queue is polled with. */
+export async function requestGeneration({
+  prompt, userKey, resolution = '768x768', negativePrompt = '', guidanceScale = 7, seed = -1,
+  requestImpl = h2Json,
+}) {
+  const requestId = randomId();
+  const query = new URLSearchParams({ userKey, requestId, adAccessCode: '', __cacheBust: randomId() });
+  const body = JSON.stringify({
+    prompt: String(prompt), negativePrompt, seed, resolution, guidanceScale,
+    channel: CHANNEL, subChannel: 'public', userKey, adAccessCode: '', requestId,
+  });
+
+  const r = await requestImpl(`${HOST}/api/generate?${query}`, {
+    method: 'POST',
+    headers: { origin: HOST, referer: `${HOST}/`, 'content-type': 'text/plain;charset=UTF-8' },
+    body,
+  });
+  if (!r.ok) return { ok: false, error: r.error ?? `generate returned ${r.status}`, challenged: r.challenged === true };
+
+  const status = r.json?.status;
+  /**
+   * ⚠️ `invalid_parameter` IS OUR BUG, NOT AN OUTAGE, and saying so saves the
+   * next person the afternoon it cost me. It means the body shape drifted — the
+   * endpoint is reachable and answering.
+   */
+  if (status === 'invalid_parameter') {
+    return { ok: false, error: 'perchance rejected the request shape (invalid_parameter) — the private API changed and lib/perchance.mjs needs re-capturing; this is not a transient failure and retrying will not help' };
+  }
+  /**
+   * ⚠️⭐ THE REQUEST IS SYNCHRONOUS AND I BUILT A QUEUE FOR NOTHING.
+   *
+   * The browser capture showed `getUserQueuePosition` being polled, so I wrote a
+   * poller — and it sat there reading `not_in_queue` for ninety seconds while
+   * the image had been ready the whole time. The POST itself returns
+   * `{ status:"success", imageId, imageDownloadUrl, seed, width, height,
+   * maybeNsfw }` in **2.7 seconds**. The queue only appears when a previous
+   * request of yours is still running, which is why the browser hit it and a
+   * fresh caller does not.
+   *
+   * ⭐ Reading the capture is not the same as reading the RESPONSE. I had every
+   * field I needed in the first reply and threw all but one of them away.
+   */
+  return {
+    ok: true,
+    requestId,
+    status: status ?? null,
+    imageId: r.json?.imageId ?? null,
+    downloadPath: r.json?.imageDownloadUrl ?? null,
+    seed: r.json?.seed ?? null,
+    // Surfaced, not swallowed: the caller is writing this into someone's page.
+    maybeNsfw: r.json?.maybeNsfw === true,
+    fileExtension: r.json?.fileExtension ?? null,
+  };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Poll until the image exists.
+ *
+ * ⚠️ BOUNDED BY WALL CLOCK, NOT BY ATTEMPTS. A queue that says "position 4"
+ * forever is indistinguishable from a broken one, and an unbounded poll inside a
+ * coding agent's round is how a session disappears.
+ */
+export async function awaitImage({ userKey, requestId, budgetMs = DEFAULT_BUDGET_MS, requestImpl = h2Json, sleepImpl = sleep }) {
+  const deadline = Date.now() + budgetMs;
+  let lastStatus = null;
+
+  while (Date.now() < deadline) {
+    const q = new URLSearchParams({ userKey, requestId });
+    const r = await requestImpl(`${HOST}/api/getUserQueuePosition?${q}`, { headers: { origin: HOST, referer: `${HOST}/` } });
+    if (!r.ok) return { ok: false, error: r.error ?? `queue poll returned ${r.status}` };
+
+    lastStatus = r.json?.status ?? null;
+    if (lastStatus === 'success') return { ok: true, imageId: r.json?.imageId ?? null, raw: r.json };
+    if (r.json?.havingTechnicalDifficulties === true) {
+      return { ok: false, error: 'perchance reports technical difficulties on its own side — not our request; use another provider for now' };
+    }
+    await sleepImpl(POLL_INTERVAL_MS);
+  }
+  return { ok: false, error: `no image within ${Math.round(budgetMs / 1000)}s (last status: ${lastStatus ?? 'none'}) — use another provider rather than waiting again` };
+}
+
+/**
+ * Fetch the finished bytes.
+ *
+ * ⚠️ THE PATH COMES FROM THE RESPONSE, NOT FROM US. `imageDownloadUrl` carries a
+ * signed token; reconstructing the URL from an imageId gets a rejection, and
+ * hand-building URLs for someone else's private API is how this breaks silently
+ * the next time they rotate the signing scheme.
+ */
+export async function downloadImage({ downloadPath, requestImpl = h2Request }) {
+  if (!downloadPath) return { ok: false, error: 'no download path in the generate response' };
+  const url = downloadPath.startsWith('http') ? downloadPath : `${HOST}${downloadPath}`;
+  const r = await requestImpl(url, { headers: { origin: HOST, referer: `${HOST}/` } });
+  if (!r.ok) return { ok: false, error: r.error ?? `download returned ${r.status}` };
+
+  const bytes = r.body;
+  /**
+   * ⚠️ MAGIC BYTES, NOT STATUS. The same rule the Pollinations path had to
+   * learn: a 200 carrying an error page written to disk as `hero.jpg` is worse
+   * than an outage, because the page looks built and is broken.
+   */
+  const isJpeg = bytes?.[0] === 0xff && bytes?.[1] === 0xd8;
+  const isPng = bytes?.subarray(0, 4).toString('hex') === '89504e47';
+  if (!bytes || bytes.length < 1000 || (!isJpeg && !isPng)) {
+    return { ok: false, error: `perchance returned ${bytes?.length ?? 0} bytes that are not an image` };
+  }
+  return { ok: true, bytes, mimeType: isJpeg ? 'image/jpeg' : 'image/png' };
+}
+
+/** The whole flow, start to bytes. */
+export async function generateNative({ prompt, resolution = '768x768', budgetMs = DEFAULT_BUDGET_MS, userKey = null } = {}) {
+  if (!prompt || !String(prompt).trim()) return { ok: false, error: 'an image needs a prompt' };
+
+  let key = userKey;
+  if (!key) {
+    const v = await verifyUser();
+    if (!v.ok) return v;
+    key = v.userKey;
+  }
+
+  const started = await requestGeneration({ prompt, userKey: key, resolution });
+  if (!started.ok) return started;
+
+  /**
+   * ⭐ THE COMMON PATH IS SYNCHRONOUS — the image is ready in the POST reply.
+   * The queue is the exception, entered only when a previous request of this
+   * userKey is still running, so it is a fallback rather than the main road.
+   */
+  let downloadPath = started.downloadPath;
+  let { maybeNsfw, seed } = started;
+
+  if (!downloadPath) {
+    const waited = await awaitImage({ userKey: key, requestId: started.requestId, budgetMs });
+    if (!waited.ok) return waited;
+    downloadPath = waited.raw?.imageDownloadUrl ?? null;
+    if (!downloadPath) return { ok: false, error: 'perchance reported success without a download url — the response shape changed' };
+    maybeNsfw = waited.raw?.maybeNsfw === true;
+    seed = waited.raw?.seed ?? null;
+  }
+
+  const got = await downloadImage({ downloadPath });
+  if (!got.ok) return got;
+
+  return { ok: true, bytes: got.bytes, mimeType: got.mimeType, provider: 'perchance-native', userKey: key, seed, maybeNsfw };
+}