Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

6.6 KB
Raw Blame
/**
 * Behaviour telemetry — delivery.
 *
 * Reads the outbox written by `aggregate.ts` at exit and POSTs each session
 * aggregate to the deployed endpoint. Runs in the BACKGROUND of a later session,
 * never on the shutdown path, because shutdown cannot await a network call.
 *
 * ## Server contract (deployed)
 *
 *   POST https://claudish.com/v1/behavior
 *   auth:  none
 *   limit: 60 accepted requests per source per minute
 *   202 — stored; a duplicate delivery gets the same response (idempotent on session_id)
 *   400 — malformed; never retried
 *   429 — rate limited, carries Retry-After
 *   5xx — server fault; at most one retry, then dropped
 *
 * Every failure mode is silent by design. This is diagnostic data about model
 * behaviour; it is never worth a word on the user's terminal, let alone an
 * error. Note also that claudish shares stdio with the Claude Code TUI, so a
 * stray write here would corrupt its rendering.
 */

import { readFile, rename, unlink, writeFile } from "node:fs/promises";
import { log } from "../../logger.js";
import type { SessionReport } from "./aggregate.js";
import { outboxPath } from "./aggregate.js";

const ENDPOINT = "https://claudish.com/v1/behavior";

/**
 * Deliberately more generous than the 3s `/v1/report` uses.
 *
 * That endpoint is fire-and-forget on the request path, where a slow call would
 * make the user wait, so a tight timeout is right. This drain runs in the
 * BACKGROUND and blocks nothing, so the same 3s buys nothing and costs real
 * deliveries: measured against the deployed service, a warm request completes in
 * ~600ms but a COLD start exceeds 3s. At 3s the first drain after an idle period
 * fails every time, and reports only ever land on a second run.
 */
const REQUEST_TIMEOUT_MS = 15_000;

/**
 * Spacing between deliveries. The server accepts 60/minute; 1.1s keeps a drained
 * backlog comfortably inside that without needing to read the response headers
 * to find out we have already exceeded it.
 */
const SEND_INTERVAL_MS = 1100;

/**
 * Ceiling on a single drain. A backlog larger than this is not worth the wall
 * clock — the data is aggregate and the oldest entries are the least useful.
 */
const MAX_DRAIN_PER_RUN = 50;

/**
 * Ceiling on the retained outbox. Reached only if a machine is offline for a
 * long stretch; oldest entries are dropped first for the same reason the journal
 * prunes oldest-first — a record of a claudish version no longer in use
 * describes a system that no longer exists.
 */
const MAX_OUTBOX_ENTRIES = 200;

type Outcome = "sent" | "drop" | "retry";

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

/**
 * Deliver one report.
 *
 * @returns `sent` on 202, `drop` when the report can never succeed, `retry`
 *          when it should stay in the outbox for a later run.
 */
async function post(report: SessionReport): Promise<Outcome> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
  try {
    const res = await fetch(ENDPOINT, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(report),
      signal: controller.signal,
    });

    if (res.status === 202) return "sent";

    // Malformed by the server's judgement. Retrying an identical body would
    // fail identically forever, so this is a client bug to fix, not a transient
    // fault to absorb.
    if (res.status === 400) {
      log("[behavior:telemetry] rejected as malformed (400), dropping");
      return "drop";
    }

    // We cannot honour Retry-After by waiting — a drain runs in the background
    // of someone's coding session and must not sit on a timer for a minute. The
    // report keeps for the next run, which is the same outcome, later.
    if (res.status === 429) {
      log("[behavior:telemetry] rate limited, deferring to next run");
      return "retry";
    }

    return res.status >= 500 ? "retry" : "drop";
  } catch {
    // Offline, DNS failure, timeout. All transient.
    return "retry";
  } finally {
    clearTimeout(timer);
  }
}

/** Parse the outbox, discarding any line that is not a usable report. */
function parseOutbox(content: string): SessionReport[] {
  const out: SessionReport[] = [];
  for (const line of content.split("\n")) {
    if (!line.trim()) continue;
    try {
      const parsed = JSON.parse(line);
      if (parsed && typeof parsed.session_id === "string") out.push(parsed);
    } catch {
      // A torn line from an interrupted append. Skipping it is correct; there is
      // nothing to recover and one bad line must not block the whole outbox.
    }
  }
  return out;
}

/** Rewrite the outbox with what remains, via temp + rename so a reader never sees a partial file. */
async function persistRemaining(path: string, remaining: SessionReport[]): Promise<void> {
  if (remaining.length === 0) {
    await unlink(path).catch(() => {});
    return;
  }
  const kept = remaining.slice(-MAX_OUTBOX_ENTRIES);
  const tmp = `${path}.draining`;
  await writeFile(tmp, `${kept.map((r) => JSON.stringify(r)).join("\n")}\n`);
  await rename(tmp, path);
}

let drained = false;

/**
 * Deliver the outbox. Safe to call repeatedly — it runs at most once per process.
 *
 * Never throws and is never awaited by the request path.
 */
export async function drainOutbox(path = outboxPath()): Promise<{ sent: number; kept: number }> {
  if (drained) return { sent: 0, kept: 0 };
  drained = true;

  try {
    const content = await readFile(path, "utf8").catch(() => "");
    const reports = parseOutbox(content);
    if (reports.length === 0) return { sent: 0, kept: 0 };

    // Newest first: if the backlog exceeds one drain, recent sessions are the
    // ones worth delivering.
    const batch = reports.slice(-MAX_DRAIN_PER_RUN).reverse();
    const older = reports.slice(0, Math.max(0, reports.length - MAX_DRAIN_PER_RUN));

    const keep: SessionReport[] = [];
    let sent = 0;
    for (let i = 0; i < batch.length; i++) {
      if (i > 0) await sleep(SEND_INTERVAL_MS);
      const outcome = await post(batch[i]);
      if (outcome === "sent") sent++;
      else if (outcome === "retry") keep.push(batch[i]);
      // "drop" falls through: neither sent nor kept.
    }

    await persistRemaining(path, [...older, ...keep]);
    if (sent > 0) log(`[behavior:telemetry] delivered ${sent} session report(s)`);
    return { sent, kept: keep.length };
  } catch (err) {
    log(`[behavior:telemetry] drain failed: ${err}`);
    return { sent: 0, kept: 0 };
  }
}

/** Test seam — re-arms the once-per-process guard. */
export function resetDrainState(): void {
  drained = false;
}