cartethyia 2.4.6 → 2.5.0

package/src/config/cooldowns.ts

@@ -1,138 +1,138 @@
-/**
- * Account/pool health cooldown fallback resolvers.
- */
-
-import { CONFIG_SPEC, readInt } from "./spec";
-
-/** Fallback cooldown for a provider rate limit (default 15m). */
-export function resolveAccountRateLimitCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS,
-  );
-}
-
-/**
- * Fallback cooldown for provider quota exhaustion when the error states no
- * reset window (default 1h). A provider-specific rule (xAI Grok Build's
- * rolling 24-hour free-tier window) overrides it inside the classifier.
- */
-export function resolveAccountQuotaCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS,
-  );
-}
-
-/** Fallback cooldown for model-capacity overload (default 2m). */
-export function resolveAccountModelCapacityCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS,
-  );
-}
-
-/** Backoff for a transient 5xx/network fault, recorded as `cooldown` (default 30s). */
-export function resolveAccountTransientCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS,
-  );
-}
-
-/** Backoff for a failure no rule matched, recorded as `cooldown` (default 1m). */
-export function resolveAccountUnclassifiedCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS,
-  );
-}
-
-/**
- * Ceiling an escalated fallback cooldown may reach (default 1h).
- *
- * A fallback duration is one the provider never stated, so escalating it is our
- * own estimate. The cap keeps that estimate from outliving a short transient
- * window: an account that recovers on its own must not sit parked for a day
- * because a burst of 5xx happened to arrive while it was already cooling.
- */
-export function resolveAccountCooldownEscalationMaxMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS,
-  );
-}
-
-/** How long a proxy pool stays `cooldown` after a transport fault (default 2m). */
-export function resolvePoolCooldownMs(): number {
-  return readInt("CARTETHYIA_POOL_COOLDOWN_MS", CONFIG_SPEC.CARTETHYIA_POOL_COOLDOWN_MS);
-}
-
-/**
- * Backoff for an auth rejection that names no revocation (default 5m).
- *
- * A bare `401`/`403` is weak evidence: it covers clock skew, a key rotated
- * upstream a moment ago, an edge cache, and a load balancer that answers before
- * the credential is loaded. None of those is the credential's death, and this
- * outcome used to be `disabled` — the one state no sweep recovers, so the
- * account left rotation until an operator noticed. A cooldown costs the same
- * requests for five minutes and comes back on its own.
- *
- * Only a *named* revocation (`token revoked`, `invalidated oauth token`) still
- * parks the account: the upstream stated the credential itself is dead, there is
- * no expiry to wait out and no refresh to run, so a cooldown would only return
- * it to rotation to fail again. Set this to `0` to restore the old behavior.
- */
-export function resolveAccountAuthRejectedCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS,
-  );
-}
-
-/**
- * Base backoff for the buddy policy/channel block (`11140`, `11128`) (default 5m).
- *
- * Deliberately a *base*, not the 24h flat penalty it replaced. `11140` has two
- * documented causes our classifier cannot separate from the response alone: the
- * user's prompt failed a safety review, **and** sending the wrong desktop
- * `User-Agent` brand (`workbuddy/shared.ts`). A flat 24h meant that after we
- * fixed a header regression every buddy account stayed dead for up to a further
- * day, and one unsafe prompt cost a whole account a day.
- *
- * As a base it escalates through the consecutive-failure ladder instead, which
- * distinguishes the two causes by what they do next: a genuinely blocked account
- * is refused again on its very next request and parks itself within minutes,
- * while a single bad prompt costs five minutes.
- */
-export function resolveAccountPolicyBlockCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS,
-  );
-}
-
-/**
- * How long an **automatically** disabled account stays out of rotation (default 24h).
- *
- * `disabled` used to be terminal: nothing recovered it, so a credential rejected
- * once — a revoked key, a definitively dead refresh grant — left rotation until an
- * operator noticed and clicked Recover by hand. That is the wrong default for a
- * credential that may come back on its own: keys get re-issued, grants get
- * re-authorized, and an upstream's notion of "invalid" can outrun ours.
- *
- * The deadline is what makes this safe to automate rather than a policy guess. A row
- * this gateway disables **by itself** carries the deadline; a row an **operator**
- * disables keeps `cooldownUntil` null, and the recovery sweep selects only rows whose
- * deadline has elapsed. So an operator's decision still outranks the machine, with no
- * extra column and no way to confuse the two.
- *
- * Long on purpose: the states that reach here are the ones where retrying sooner
- * only reproduces the refusal. Set to `0` to restore the old terminal behavior.
- */
-export function resolveAccountDisabledRecoveryMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS,
-  );
-}
+/**
+ * Account/pool health cooldown fallback resolvers.
+ */
+
+import { CONFIG_SPEC, readInt } from "./spec";
+
+/** Fallback cooldown for a provider rate limit (default 15m). */
+export function resolveAccountRateLimitCooldownMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS,
+  );
+}
+
+/**
+ * Fallback cooldown for provider quota exhaustion when the error states no
+ * reset window (default 1h). A provider-specific rule (xAI Grok Build's
+ * rolling 24-hour free-tier window) overrides it inside the classifier.
+ */
+export function resolveAccountQuotaCooldownMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS,
+  );
+}
+
+/** Fallback cooldown for model-capacity overload (default 2m). */
+export function resolveAccountModelCapacityCooldownMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS,
+  );
+}
+
+/** Backoff for a transient 5xx/network fault, recorded as `cooldown` (default 30s). */
+export function resolveAccountTransientCooldownMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS,
+  );
+}
+
+/** Backoff for a failure no rule matched, recorded as `cooldown` (default 1m). */
+export function resolveAccountUnclassifiedCooldownMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS,
+  );
+}
+
+/**
+ * Ceiling an escalated fallback cooldown may reach (default 1h).
+ *
+ * A fallback duration is one the provider never stated, so escalating it is our
+ * own estimate. The cap keeps that estimate from outliving a short transient
+ * window: an account that recovers on its own must not sit parked for a day
+ * because a burst of 5xx happened to arrive while it was already cooling.
+ */
+export function resolveAccountCooldownEscalationMaxMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS,
+  );
+}
+
+/** How long a proxy pool stays `cooldown` after a transport fault (default 2m). */
+export function resolvePoolCooldownMs(): number {
+  return readInt("CARTETHYIA_POOL_COOLDOWN_MS", CONFIG_SPEC.CARTETHYIA_POOL_COOLDOWN_MS);
+}
+
+/**
+ * Backoff for an auth rejection that names no revocation (default 5m).
+ *
+ * A bare `401`/`403` is weak evidence: it covers clock skew, a key rotated
+ * upstream a moment ago, an edge cache, and a load balancer that answers before
+ * the credential is loaded. None of those is the credential's death, and this
+ * outcome used to be `disabled` — the one state no sweep recovers, so the
+ * account left rotation until an operator noticed. A cooldown costs the same
+ * requests for five minutes and comes back on its own.
+ *
+ * Only a *named* revocation (`token revoked`, `invalidated oauth token`) still
+ * parks the account: the upstream stated the credential itself is dead, there is
+ * no expiry to wait out and no refresh to run, so a cooldown would only return
+ * it to rotation to fail again. Set this to `0` to restore the old behavior.
+ */
+export function resolveAccountAuthRejectedCooldownMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS,
+  );
+}
+
+/**
+ * Base backoff for the buddy policy/channel block (default 5m).
+ *
+ * Deliberately a *base*, not the 24h flat penalty it replaced. `11140` has two
+ * documented causes our classifier cannot separate from the response alone: the
+ * user's prompt failed a safety review, **and** sending the wrong desktop
+ * `User-Agent` brand (`workbuddy/shared.ts`). A flat 24h meant that after we
+ * fixed a header regression every buddy account stayed dead for up to a further
+ * day, and one unsafe prompt cost a whole account a day.
+ *
+ * As a base it escalates through the consecutive-failure ladder instead, which
+ * distinguishes the two causes by what they do next: a genuinely blocked account
+ * is refused again on its very next request and parks itself within minutes,
+ * while a single bad prompt costs five minutes.
+ */
+export function resolveAccountPolicyBlockCooldownMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS,
+  );
+}
+
+/**
+ * How long an **automatically** disabled account stays out of rotation (default 24h).
+ *
+ * `disabled` used to be terminal: nothing recovered it, so a credential rejected
+ * once — a revoked key, a definitively dead refresh grant — left rotation until an
+ * operator noticed and clicked Recover by hand. That is the wrong default for a
+ * credential that may come back on its own: keys get re-issued, grants get
+ * re-authorized, and an upstream's notion of "invalid" can outrun ours.
+ *
+ * The deadline is what makes this safe to automate rather than a policy guess. A row
+ * this gateway disables **by itself** carries the deadline; a row an **operator**
+ * disables keeps `cooldownUntil` null, and the recovery sweep selects only rows whose
+ * deadline has elapsed. So an operator's decision still outranks the machine, with no
+ * extra column and no way to confuse the two.
+ *
+ * Long on purpose: the states that reach here are the ones where retrying sooner
+ * only reproduces the refusal. Set to `0` to restore the old terminal behavior.
+ */
+export function resolveAccountDisabledRecoveryMs(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS,
+  );
+}

package/src/config/providers.ts

@@ -4,7 +4,7 @@
  * callback URL builders built on the public origin.
  */
 
-import { CONFIG_SPEC, readList, readRequired, readText } from "./spec";
+import { CONFIG_SPEC, readInt, readList, readRequired, readText } from "./spec";
 
 /** Reads and normalizes the public OAuth origin. */
 export function requirePublicOrigin(): string {
@@ -22,14 +22,14 @@ export function oauthCallbackUrl(providerId: string): string {
 /**
  * Browser-authorize redirect URI for a provider.
  *
- * Browser OAuth always advertises the loopback callback
- * `http://127.0.0.1:59653/callback` — the URI Codex registers with its
- * authorization server. The console callback stays the exchange
+ * Browser OAuth advertises a loopback callback, `http://127.0.0.1:59653/callback`
+ * by default — the URI Codex registers with its authorization server, which is
+ * why the port is the default rather than a free one. The console callback stays the exchange
  * endpoint: the dashboard dialog pastes the loopback landing URL back and
  * the server exchanges the code against the same loopback URI.
  */
 export function browserAuthorizeRedirectUri(): string {
-  return "http://127.0.0.1:59653/callback";
+  return `http://127.0.0.1:${readInt("CARTETHYIA_OAUTH_CALLBACK_PORT", CONFIG_SPEC.CARTETHYIA_OAUTH_CALLBACK_PORT)}/callback`;
 }
 
 /**

package/src/config/runtime.ts

@@ -51,10 +51,26 @@ export function resolveDrainToken(): string | undefined {
 }
 
 /**
- * Whether Elysia precompiles route handlers at startup (AOT). On in production,
- * off in development, where just-in-time compilation keeps `--hot` reloads
- * fast. The standalone `bun run build:aot` artifact is unaffected.
+ * Whether Elysia precompiles route handlers at startup (AOT).
+ *
+ * Precompilation takes the eager validator branch, which calls TypeBox's
+ * `SchemaCompile(schema)` and then reads `.buildResult.external` off the
+ * result. In a source-run process that field is absent — the lazy
+ * `require("typebox/schema")` resolves to a namespace that does not carry it —
+ * and the process dies at the first schema-bearing route with
+ * `undefined is not an object (evaluating 'this.tb.buildResult.external')`.
+ * `scripts/binary/aot.ts` avoids this by rewriting the call site and bundling
+ * the namespaces statically, so only the built artifact can actually take the
+ * eager path.
+ *
+ * So: precompilation is on for production *builds*, and off for a source run
+ * even when `NODE_ENV=production`. A deployment that runs
+ * `bun run src/main.ts` must not be pushed onto the eager branch.
+ *
+ * `CARTETHYIA_SOURCE_RUN` marks a source run explicitly. It is set by
+ * `scripts/deploy/*.sh`, which are the only supported way to run from source.
  */
 export function resolveElysiaPrecompile(): boolean {
+  if (process.env.CARTETHYIA_SOURCE_RUN === "1") return false;
   return process.env.NODE_ENV === "production";
 }

package/src/config/spec.ts

@@ -213,6 +213,15 @@ export const CONFIG_SPEC = {
 
   // Provider OAuth hosts
   CARTETHYIA_KIMI_OAUTH_HOST: { kind: "text", default: DEFAULT_KIMI_OAUTH_HOST },
+  /**
+   * Loopback port the browser-OAuth callback listener binds.
+   *
+   * Configurable because the default is a fixed number and a busy port used to
+   * strand the operator: the login could not start and there was no way to move
+   * it. Codex's authorization server still expects 59653, so changing this
+   * only helps the providers whose redirect URI is not allowlisted upstream.
+   */
+  CARTETHYIA_OAUTH_CALLBACK_PORT: { kind: "int", default: 59_653, min: 1_024, max: 65_535 },
   /**
    * Kimi Code quota/billing base. The `/usages` path joins on this, so the
    * default includes the `/v1` segment the bundled provider metadata implies.