Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

13.0 KB
Raw Blame

Compass weekly allowance and sharing reward rollout

Implementation spans webbrain2 and sibling webbrain-cloud. The constructor default and example configuration are now $0.50 per UTC week, resetting Monday at 00:00 UTC. Production activation is a separate rollout step; no production deployment was performed during implementation or PR preparation.

Release order

  1. Backend compatibility first. Back up the entire usage JSON while the service is stopped or while holding its store lock. Set WEEKLY_FREE_USD=0.50 explicitly in the active backend environment for the approved transition while clients update. The constructor default also matches $0.50. Ship the additive usage fields, /usage (/v1/usage alias), promotion endpoints, persistent ledger, review CLI, and telemetry first. Older clients retain their existing Subscribe card until they update. Verify a free-quota 402 still includes the device-linked subscribe_url, and paid/payment-failure responses still point to the existing upgrade/account flows. Confirm the CLI and web workers resolve the same USAGE_PATH, and that all workers share the same filesystem lock.
  2. Extension next. Ship both Chrome and Firefox together. While the sharing reward is paused (see below) the card has no reward choice, claim form or claim status, so the reward and claim checks in this step apply only when it is enabled. Check the reward and subscription choices, narrow panels, keyboard focus, claim submission/status, restored conversations, and a return from checkout. Confirm an automatic award leaves browser actions stopped until the explicit Continue/Retry button is selected. Confirm pending claims from older versions are automatically accepted when status is fetched, approved/redeemed devices have no offer to earn again, and existing payment recovery and Plus upgrades still work. Confirm the backend returns promotion state before enabling the new experience to users.
  3. Verify the transition amount. Check the actual web-worker/service/container environment as well as .env: exported variables take precedence over .env. Query /usage from the running service with X-WebBrain-Device-Id; both base_weekly_allowance_usd and weekly_limit_usd must be 0.50, and next_reset_at must be the next Monday 00:00 UTC. Verify an exhausted free device's 402 reports the same amount and retains subscribe_url. Do not rely on the example file or a CLI process with a different environment. Keep the explicit $0.50 override while clients adopt the update. A later reduction to $0.375 requires a separate rollout decision after reviewing extension availability, adoption, and consumption; it is not activated automatically.
  4. Observe for 14 full days at $0.50. Record the UTC activation time, active amount, extension versions, and automatic reward behavior. Review the report daily and reassess the amount after two full UTC weeks. If recovery choices are unavailable or the allowance proves too small, restore the override to 0.75 while leaving the backend ledger and extension controls in place. A rollback must preserve lifetime awards and remaining balances.

Local configuration inspected on 2026-10-05: neither the process environment nor the local cloud .env sets WEEKLY_FREE_USD; the effective local value is now 0.50. Production activation must be verified separately using the running web service.

The backend now uses a stable USAGE_PATH.lock and atomically replaces the usage JSON. For the first upgrade from the old in-place writer, stop and drain all old web workers and review/report CLI processes before starting the new version; do not mix the two lock protocols. Confirm the store owner can create the lock and temporary files and replace the JSON on the same filesystem. Never remove the lock file while any worker is running. Keep the explicit 0.50 transition override throughout this backend migration and client adoption.

Production storage must support POSIX directory fsync: verify file and parent-directory syncing on the actual usage-store filesystem. Windows PHP cannot sync directory handles; its local validation covers process interruptions, while the Linux durability test exercises directory-sync failures and idempotent retries. Client telemetry is best-effort and globally capped at 10,000 retained device/day observations; excess events return recorded: false. Actual metered consumption and lifetime awards are independent of that telemetry cap.

Sharing reward paused

The extension hides the sharing reward: SOCIAL_PROMOTION_ENABLED in src/*/src/ui/compass-quota.js is false, because the offer invited abuse. The quota card then shows the weekly allowance (quota.allowance), the reset time, Subscribe, Refresh status and Continue/Retry. It never requests /promotions/social, shows no claim status, and a restored card that had its claim form open comes back without it. Credit a device already earned still appears as the reward balance, and the backend still spends it. The claim flow below is unchanged and still tested (test/compass-quota-ui.mjs mounts it with socialPromotion: true); setting the flag back to true in both builds, and the expectation that pins it in test/compass-quota.mjs, restores it. While it is paused, Continue/Retry sends no continuation_after_reward event, and a balance that would print as $0.00 counts as none.

The extension switch alone does not stop the reward. The backend still accepts POST /promotions/social/claims and awards $0.50 automatically for any syntactically valid post URL under any X-WebBrain-Device-Id, /usage still approves leftover pending claims, and extension versions released before this switch still show the offer. Pausing it for every client needs a server-side switch in webbrain-cloud: refuse new claims, stop automatic approval, and report eligible: false (older extension versions hide the share button then), while earned balances stay spendable.

Automatic rewards

A syntactically valid supported public post URL submitted to /promotions/social/claims immediately grants the one-time $0.50 reward under the usage-store lock. The response is already approved, with eligible: false and a $0.50 balance. With the reward enabled, the quota card offers sharing credit and a Compass subscription; while it is paused it offers only the subscription. It has no provider-switch choice.

Existing pending claims receive the same award on /usage, /v1/usage, /promotions/social, or a repeated submission. Drafts and rejected claims receive no credit until submitted. Ordinary usage reads still do not allocate claims or rewrite the ledger. Deploy this backend behavior before the extension copy.

The lifetime device award, normalized post index, balance, and approval event are written atomically. Repeated submission of the same normalized post returns the existing result, including after redemption, without replenishing credit. Different posts from an awarded device and duplicate posts across devices remain blocked. Concurrent submissions cannot grant twice. Unused credit carries across weeks.

Users publish their posts themselves. LinkedIn opens its link-sharing composer; the editable text can be copied into it. X and Bluesky composers receive the edited text. Supported links include X/Twitter status URLs, LinkedIn activity URLs, and Bluesky profile/post URLs. Query tracking and fragments are discarded.

Automatic acceptance validates URL syntax and deduplicates the submitted post; it does not fetch post content or resolve canonical author identities. New awards record verification: automatic_submission. Existing manually verified author/post indexes remain preserved. The review CLI remains available for legacy administration, but no approval command or reviewer attestation is required by the current claim flow.

Accounting and compatibility

socialPromotions is a persistent top-level section of the existing usage JSON. It holds device claim IDs, claims/revisions, lifetime awards, post/profile indexes, pending-post reservations, balances, and counters. Weekly cleanup only removes weeks; it never removes the promotion ledger or awards. Maintain backups of the whole file, and keep it outside public web roots. A corrupt store fails closed for grants and consumption instead of resetting award history.

Readers and writers coordinate on the same stable lock file. A write is committed only by replacing the JSON after fully writing and syncing a temporary file; interruptions before replacement preserve the prior ledger, and interruptions after replacement are safe to retry. Temporary files left by a killed worker are never treated as the ledger. An existing empty store is corruption: restore a verified backup while workers are stopped instead of initializing fresh lifetime awards. Any rollback must retain the new locking protocol or stop and drain all workers before changing it.

Each weekly device entry keeps actual usd and a separate promotionalSpentUsd. The recurring allowance is consumed first. Only the newly metered excess debits the remaining reward, capped by the balance. Reward credit does not expire on Monday. Usage is never reduced to conceal promotional spending, and already incurred overshoot is not retroactively charged when a reward is granted. Requests already admitted can finish above an allowance, as with the existing metered quota; concurrent completion cannot overdraft the promotion balance. Paid limits and upgrade behavior continue to use total metered cost.

Each request keeps the tier resolved at admission for model and visual usage recording, so a later billing outage or entitlement change cannot reclassify its promotional spending.

/usage and quota usage payloads add base_weekly_allowance_usd, promotional_balance_usd, promotional_spent_usd, social_claim, and next_reset_at. Existing weekly/daily aliases and billing URLs remain present. The UI formats fractional USD without turning $0.375 into $0.38 or $0.37. Public share links contain only random claim IDs, never the device GUID. Quota metadata crosses provider errors, the background event journal, terminal replay, and persisted quota-card datasets. Draft copy, selected platform, post URL, failed run mode, foreground behavior, and the Continue/Retry decision survive history restoration.

Telemetry and the two-week decision

php scripts/report-social-promotion.php --days=14

The report contains quota-card views, checkout opens, server-recorded claim submissions and successful grants, explicit continuation after a reward, historical provider switches, and subscription conversions. A conversion is counted once when a device that opened checkout is observed with a paid entitlement on /usage; checkout opens alone do not count as conversions. Client counts are capped per device/day and are event totals rather than unique-person counts.

Metered consumption is recorded under the same store lock from actual completed token usage, including visual sidecars. Numeric samples use hashed device/session identifiers and retain 30 UTC days; no prompt, post body, or page content is added to these samples. Each consumption map retains at most 10,000 observations across retained dates; existing samples continue accumulating, and new keys contribute to overflow totals. Exact metered aggregates remain intact. The report discloses observation counts and overflow USD/requests in sampling; inspect that coverage before using the sampled distributions to change the allowance. The 14-day report shows free-session and free-device/week p50/p75/p90/p95 costs and fraction_over_allowance for the active amount. It retains fraction_over_0_375 for evaluating the previously proposed reduction. Calls without a session identifier contribute to unattributed_usd, so report that coverage gap. Device/week distributions use completed Monday–Sunday UTC weeks independently of the rolling event/session window. With --days=14, verify device_week_window reports two completed weeks after activation, inspect its retained overflow/untagged coverage totals, and wait until both weeks have full instrumentation. A partly expired retention-boundary week is omitted; reports shorter than seven days have no completed weekly distribution. Admission-week tags keep requests that finish after reset in their original UTC week. Lifetime claims/indexes are not subject to sample retention.

Reassess whether $0.50 covers useful completed sessions, how many device/weeks exhaust it, how often rewards lead to explicit continuation, how many users subscribe, and whether pending claims recover automatically. Use actual consumption distributions and recovery/conversion behavior to decide whether to keep $0.50, raise it, or propose a separately approved reduction to $0.375 once adoption and consumption support it. Do not equate views or composer opens with published posts or successful tasks.

Validation

See compass-quota-validation.md for executed checks, artifacts, and remaining environment-specific failures. Local browser fixtures simulate automatic awards and checkout return; no social posts, purchases, or production changes were made.