Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
16.7 KB
Raw Blame
/**
 * Quality rewards: the `quality` block on /device/me, the wheel's
 * segments (GET /me/quality) and a spin (POST /me/quality/spin).
 *
 * `quality: null` means the feature is switched off: the app shows nothing.
 * The server picks every spin's outcome; the app only animates the wheel to
 * `segment_index`.
 */

export const QUALITY_TIERS = /** @type {const} */ (["new", "standard", "gold", "coaching", "limited"]);
export const SPIN_REFUSALS = /** @type {const} */ (["no_spins", "wheel_resting", "quality_rewards_off"]);

/**
 * @typedef {{ id: string, kind: string | null, title: string, body: string }} QualityNotice
 * @typedef {{
 *   tier: typeof QUALITY_TIERS[number],
 *   score: number,
 *   tokensMultiplier: number,
 *   spinsAvailable: number,
 *   reproSpinsAvailable: number,
 *   clientSpinsAvailable: number,
 *   spinsExpireAt: string | null,
 *   nextTierHint: string | null,
 *   tips: string[],
 *   notice: QualityNotice | null,
 *   mode: "shadow" | "enforce",
 *   resting: boolean,
 *   preview: boolean,
 *   notices: QualityNotice[],
 *   streakDays: number,
 *   streakMultiplier: number,
 *   streakNext: { days: number, bonusSpins: number } | null,
 *   nextSpinHint: { progress: number, text: string, sessionId: string | null } | null,
 *   biggestWinToday: { tokens: number, at: string | null } | null,
 *   nudge: { id: string, text: string } | null,
 *   windowsCounts: boolean,
 * }} AccountQuality
 * @typedef {{ tokens: number, weight: number }} WheelSegment
 * @typedef {{
 *   tokens: number,
 *   prizeTokens: number,
 *   segmentIndex: number,
 *   segments: WheelSegment[],
 *   preview: boolean,
 *   capped: boolean,
 *   reproducible: boolean,
 *   alreadySpun: boolean,
 *   spunAt: string | null,
 *   spinsAvailable: number,
 *   potBalance: number | null,
 *   celebrate: "none" | "big" | "jackpot",
 *   nearMiss: boolean,
 *   jackpotTokens: number | null,
 *   streakDays: number | null,
 * }} QualitySpin
 * @typedef {{ ok: true, spin: QualitySpin }
 *   | { ok: false, reason: typeof SPIN_REFUSALS[number] | "signed_out" | "unreachable" | "failed", status: number | null }} QualitySpinOutcome
 */

function text(value) {
  return typeof value === "string" && value.trim() ? value.trim() : null;
}

function count(value) {
  const number = Number(value);
  return Number.isFinite(number) && number > 0 ? Math.floor(number) : 0;
}

function isoTime(value) {
  const raw = text(value);
  return raw && Number.isFinite(Date.parse(raw)) ? raw : null;
}

/** @returns {QualityNotice | null} */
function parseNotice(value) {
  if (!value || typeof value !== "object") return null;
  const id = text(value.id);
  const title = text(value.title);
  if (!id || !title) return null;
  return { id, kind: text(value.kind), title, body: text(value.body) ?? "" };
}

function fraction(value) {
  const number = Number(value);
  return Number.isFinite(number) ? Math.min(1, Math.max(0, number)) : 0;
}

function parseStreakNext(value) {
  if (!value || typeof value !== "object") return null;
  const days = count(value.days);
  return days ? { days, bonusSpins: count(value.bonus_spins) } : null;
}

function parseNextSpinHint(value) {
  if (!value || typeof value !== "object") return null;
  const hint = text(value.text);
  return hint ? { progress: fraction(value.progress), text: hint, sessionId: text(value.session_id) } : null;
}

function parseBiggestWin(value) {
  if (!value || typeof value !== "object") return null;
  const tokens = count(value.tokens);
  return tokens ? { tokens, at: isoTime(value.at) } : null;
}

function parseNudge(value) {
  if (!value || typeof value !== "object") return null;
  const id = text(value.id);
  const message = text(value.text);
  return id && message ? { id, text: message } : null;
}

/**
 * The `quality` block of a /device/me (or /me) answer; null when the
 * feature is off, the block is missing or it names no known tier.
 * @returns {AccountQuality | null}
 */
export function parseAccountQuality(value) {
  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
  const tier = text(value.tier)?.toLowerCase();
  if (!tier || !QUALITY_TIERS.includes(/** @type {any} */ (tier))) return null;
  const score = Number(value.score);
  const multiplier = Number(value.tokens_multiplier);
  const spinsAvailable = count(value.spins_available);
  const notices = Array.isArray(value.notices) ? value.notices.map(parseNotice).filter((notice) => notice !== null).slice(0, 5) : [];
  return {
    tier: /** @type {AccountQuality["tier"]} */ (tier),
    score: Number.isFinite(score) ? Math.min(1, Math.max(0, score)) : 0,
    tokensMultiplier: Number.isFinite(multiplier) && multiplier > 0 ? multiplier : 1,
    spinsAvailable,
    reproSpinsAvailable: Math.min(spinsAvailable, count(value.repro_spins_available)),
    // Of those, earned by client-grade sessions (the richer wheel).
    clientSpinsAvailable: Math.min(spinsAvailable, count(value.client_spins_available)),
    spinsExpireAt: isoTime(value.spins_expire_at),
    nextTierHint: text(value.next_tier_hint),
    tips: Array.isArray(value.tips) ? value.tips.map(text).filter((tip) => tip !== null).slice(0, 8) : [],
    notice: notices[0] ?? parseNotice(value.notice),
    notices: notices.length ? notices : [parseNotice(value.notice)].filter((notice) => notice !== null),
    mode: value.mode === "enforce" ? "enforce" : "shadow",
    resting: value.resting === true,
    preview: value.preview === true,
    streakDays: count(value.streak_days),
    streakMultiplier: count(value.streak_multiplier),
    streakNext: parseStreakNext(value.streak_next),
    nextSpinHint: parseNextSpinHint(value.next_spin_hint),
    biggestWinToday: parseBiggestWin(value.biggest_win_today),
    nudge: parseNudge(value.nudge),
    // Native Windows counts like every other system unless the server says otherwise.
    windowsCounts: value.windows_counts !== false,
  };
}

/** @returns {WheelSegment[]} */
export function parseWheelSegments(value) {
  if (!Array.isArray(value)) return [];
  return value
    .filter((segment) => segment && typeof segment === "object")
    .map((segment) => ({ tokens: count(segment.tokens), weight: Math.max(0, Number(segment.weight) || 0) }));
}

/**
 * A 200 from POST /me/quality/spin; null when it does not name a segment
 * the wheel can land on.
 * @returns {QualitySpin | null}
 */
export function parseSpinResult(value) {
  if (!value || typeof value !== "object") return null;
  const segments = parseWheelSegments(value.segments);
  const segmentIndex = Number(value.segment_index);
  if (!Number.isInteger(segmentIndex) || segmentIndex < 0 || segmentIndex >= segments.length) return null;
  const pot = Number(value.pot_balance);
  return {
    tokens: count(value.tokens),
    prizeTokens: count(value.prize_tokens) || segments[segmentIndex].tokens,
    segmentIndex,
    segments,
    preview: value.preview === true,
    capped: value.capped === true,
    reproducible: value.reproducible === true,
    alreadySpun: value.already_spun === true,
    spunAt: isoTime(value.spun_at),
    spinsAvailable: count(value.spins_available),
    potBalance: value.pot_balance === null || value.pot_balance === undefined || !Number.isFinite(pot) ? null : Math.max(0, pot),
    celebrate: value.celebrate === "big" || value.celebrate === "jackpot" ? value.celebrate : "none",
    nearMiss: value.near_miss === true,
    jackpotTokens: count(value.jackpot_tokens) || null,
    streakDays: value.streak_days === undefined || value.streak_days === null ? null : count(value.streak_days),
    // A spin earned by a client-grade session, on the richer wheel (`segments` is the wheel used).
    clientGrade: value.client_grade === true,
  };
}

/** The `sessions` of GET /me/quality, for the coaching card's "see why". */
export function parseQualitySessions(value) {
  if (!Array.isArray(value)) return [];
  return value
    .filter((session) => session && typeof session === "object" && text(session.session_id))
    .slice(0, 50)
    .map((session) => ({
      sessionId: text(session.session_id),
      at: isoTime(session.at),
      verdict: text(session.verdict),
      why: text(session.why),
      fails: Array.isArray(session.fails) ? session.fails.map(text).filter((fail) => fail !== null) : [],
      workspace: text(session.workspace),
      spins: count(session.spins),
      counted: session.counted === true,
      // The looser reward level; `reproClient` is the strict client grade.
      reproducible: reproLevel(session.reproducible),
      reproClient: reproLevel(session.repro_client),
      clientGrade: session.client_grade === true,
      workSize: Number.isInteger(session.work_size) ? Math.min(4, Math.max(0, session.work_size)) : null,
      work: parseSessionWork(session.work),
    }));
}

function reproLevel(value) {
  return value === "pass" || value === "fail" || value === "unknown" ? value : null;
}

function parseSessionWork(value) {
  if (!value || typeof value !== "object") return null;
  return {
    codeFiles: count(value.code_files),
    linesChanged: count(value.lines_changed),
    toolCalls: count(value.tool_calls),
    testRuns: count(value.test_runs),
    floor: count(value.floor),
    step: count(value.step),
  };
}

const SPIN_STATUSES = ["ready", "spun", "expired", "forfeit"];

/** GET /me/quality/spins: the totals and the newest `limit` spins. */
export function parseSpinHistory(value, limit = 10) {
  if (!value || typeof value !== "object") return null;
  const totals = value.totals && typeof value.totals === "object" ? value.totals : {};
  const spins = Array.isArray(value.spins) ? value.spins : [];
  return {
    spun: count(totals.spun),
    paidTokens: count(totals.paid_tokens),
    recent: spins
      .filter((spin) => spin && typeof spin === "object" && text(spin.id))
      .slice(0, limit)
      .map((spin) => ({
        id: text(spin.id),
        status: SPIN_STATUSES.includes(spin.status) ? spin.status : "ready",
        reason: text(spin.reason),
        reproducible: spin.reproducible === true,
        clientGrade: spin.client_grade === true,
        sessionId: text(spin.session_id),
        earnedAt: isoTime(spin.earned_at),
        expiresAt: isoTime(spin.expires_at),
        spunAt: isoTime(spin.spun_at),
        prizeTokens: spin.prize_tokens === null || spin.prize_tokens === undefined ? null : count(spin.prize_tokens),
        paidTokens: spin.paid_tokens === null || spin.paid_tokens === undefined ? null : count(spin.paid_tokens),
      })),
  };
}

/** `fail_labels` of GET /me/quality: `{code: label}`, strings only. */
export function parseFailLabels(value) {
  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
  /** @type {Record<string, string>} */
  const labels = {};
  for (const [code, label] of Object.entries(value)) {
    const clean = text(label);
    if (clean && /^[a-z0-9_-]{1,64}$/i.test(code)) labels[code] = clean;
  }
  return labels;
}

/** A session id the profile request may name (`/device/me?session_id=`), or null. */
export function profileSessionId(value) {
  const id = text(value);
  return id && /^[A-Za-z0-9_-]{1,128}$/.test(id) ? id : null;
}

/** `{"detail": "wheel_resting"}` (or `{"detail": {"code": ...}}`) from a 409. */
export function spinRefusal(payload) {
  const detail = payload && typeof payload === "object" ? payload.detail : null;
  const code = typeof detail === "string" ? detail : detail && typeof detail === "object" ? detail.code : null;
  return SPIN_REFUSALS.includes(code) ? code : null;
}

/** A caller's key, or a fresh one: at most 64 characters, as the server requires. */
export function spinIdempotencyKey(value) {
  const key = text(value);
  return key && key.length <= 64 && /^[0-9A-Za-z._:-]+$/.test(key) ? key : globalThis.crypto.randomUUID();
}

const SESSION_STATUSES = ["on_track", "at_risk", "failing", "unknown"];
const CHECK_STATES = ["pass", "fail", "warn", "pending"];
const DOCK_MODES = ["off", "observe", "warn", "enforce"];
const DOCK_STAGES = ["none", "warn", "surcharge", "cap"];
const VERDICT_STATES = ["pending", "usable", "not_usable"];
/** The fastest the app re-asks for a session's status, and its pace when the server names none. */
export const SESSION_STATUS_MIN_POLL_SECONDS = 30;
export const SESSION_STATUS_DEFAULT_POLL_SECONDS = 60;

function oneOf(value, allowed, fallback) {
  return allowed.includes(value) ? value : fallback;
}

function nonNegative(value) {
  const number = Number(value);
  return Number.isFinite(number) && number >= 0 ? number : 0;
}

function parseDock(value) {
  if (!value || typeof value !== "object") return null;
  const weight = Number(value.weight);
  const capAt = Number(value.cap_at_tokens);
  return {
    mode: oneOf(value.mode, DOCK_MODES, "off"),
    stage: oneOf(value.stage, DOCK_STAGES, "none"),
    weight: Number.isFinite(weight) && weight > 0 ? weight : 1,
    sessionTokens: nonNegative(value.session_tokens),
    surchargeTokens: nonNegative(value.surcharge_tokens),
    capAtTokens: value.cap_at_tokens === null || value.cap_at_tokens === undefined || !Number.isFinite(capAt) ? null : capAt,
    capped: value.capped === true,
    message: text(value.message),
    link: text(value.link),
  };
}

function parseVerdict(value) {
  if (!value || typeof value !== "object") return null;
  const weight = Number(value.reward_weight);
  return {
    state: oneOf(value.state, VERDICT_STATES, "pending"),
    reasons: Array.isArray(value.reasons) ? value.reasons.map(text).filter((reason) => reason !== null) : [],
    rewardWeight: Number.isFinite(weight) ? weight : null,
  };
}

const DELIVERY_STATES = ["delivered", "not_delivered", "pending"];

function deliveryReason(value) {
  const reason = value && typeof value === "object" && !Array.isArray(value) ? value : { code: value };
  const code = text(reason.code);
  const message = text(reason.message);
  return code || message ? { code: code ?? "", message } : null;
}

/**
 * Whether the session was delivered, and why not (`delivery`); on servers
 * without that block, a not_usable verdict's reason codes; null when the
 * server says nothing.
 */
export function parseDelivery(value, verdict) {
  if (value && typeof value === "object" && !Array.isArray(value)) {
    return {
      state: oneOf(value.state, DELIVERY_STATES, "pending"),
      reasons: Array.isArray(value.reasons) ? value.reasons.map(deliveryReason).filter((reason) => reason !== null) : [],
      message: text(value.message),
    };
  }
  if (verdict?.state === "not_usable" && verdict.reasons.length) {
    return { state: "not_delivered", reasons: verdict.reasons.map((code) => ({ code, message: null })), message: null };
  }
  return null;
}

/**
 * The block's `client` switches (contract revision 2); null when absent:
 * no auto-retry, the finish guard and the one-more-turn nudge on.
 */
function parseClientSwitches(value) {
  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
  const retry = value.auto_retry && typeof value.auto_retry === "object" ? value.auto_retry : null;
  const max = Number(retry?.max);
  return {
    autoRetry: retry
      ? {
        enabled: retry.enabled === true,
        max: Number.isFinite(max) && max > 0 ? Math.min(3, Math.floor(max)) : 1,
        message: text(retry.message),
      }
      : null,
    finishGuard: value.finish_guard !== false,
    oneMoreTurn: value.one_more_turn !== false,
  };
}

/**
 * The server's status block for one session (GET /me/sessions/{id}/status,
 * or `session_status` on /device/me); null when it is missing or malformed.
 * Labels, hints and messages are the server's words, kept as given.
 */
export function parseSessionStatus(value) {
  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
  const sessionId = text(value.session_id);
  if (!sessionId) return null;
  const poll = Number(value.poll_seconds);
  const verdict = parseVerdict(value.verdict);
  return {
    sessionId,
    status: oneOf(value.status, SESSION_STATUSES, "unknown"),
    reasons: Array.isArray(value.reasons)
      ? value.reasons
        .filter((reason) => reason && typeof reason === "object" && text(reason.message))
        .map((reason) => ({ code: text(reason.code) ?? "", message: text(reason.message) }))
      : [],
    message: text(value.message),
    dock: parseDock(value.dock),
    verdict,
    delivery: parseDelivery(value.delivery, verdict),
    checklist: Array.isArray(value.checklist)
      ? value.checklist
        .filter((item) => item && typeof item === "object" && text(item.id) && text(item.label))
        .map((item) => ({ id: text(item.id), state: oneOf(item.state, CHECK_STATES, "pending"), label: text(item.label), hint: text(item.hint) ?? "" }))
      : [],
    evaluatedAt: isoTime(value.evaluated_at),
    client: parseClientSwitches(value.client),
    pollSeconds: Number.isFinite(poll) && poll > 0
      ? Math.max(SESSION_STATUS_MIN_POLL_SECONDS, Math.floor(poll))
      : SESSION_STATUS_DEFAULT_POLL_SECONDS,
  };
}