Files
PaperClipAI/ui/src/lib/utils.ts
T
Devin FoleyandPaperclip e4b119440e Show live provider reset countdowns in the viewer's timezone (#22225)
## Thinking Path

> - Paperclip manages agents and their assigned work.
> - Provider usage limits can hold that work until a reset deadline.
> - Saved wait messages expose raw timestamps, and the usage popover
shows a short weekday clock.
> - People need the remaining wait and the exact deadline in their
current timezone.
> - This pull request formats both views in the browser and updates the
countdown live.
> - The browser uses its timezone while stored messages and retry
deadlines stay unchanged.

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Provider usage limit messages and the agent usage-limit property and
popover.

**Subsystem affected**
UI presentation of provider usage limits, task notices, run details, log
events, and recovery actions.

**Current behavior**
Wait messages print `2026-11-18T20:17:34.353Z`. The usage popover shows
a short clock such as `Thu 23:00`. Neither gives a live relative
countdown. If the provider did not report a reset, the scheduler uses
the recorded failure time plus one hour.

**Proposed behavior**
A Pacific-time viewer sees `in 44 minutes (Nov 18, 2026, 12:17 PM PST)`.
The relative part counts down while the tab is visible. The usage
property and popover show the same local deadline. Expired usage windows
clear through the existing summary rules.

**Reason and benefit**
People can see how long remains without converting a timestamp or
refreshing the page. The date conversion handles daylight saving time
and local date changes.

**Breaking changes**
Displayed text and popover layout change. Stored messages, API payloads,
error codes, provider checks, and retry deadlines keep their contracts.

## What Changed

- Add an optional timezone label to the existing `formatDateTime`
helper. Existing callers keep their output.
- Share relative and exact local time formatting between provider-limit
messages and the usage popover. Unrelated text and invalid timestamps
stay intact.
- Reuse the existing shared one-second ticker. Countdown updates pause
in hidden tabs, catch up when shown, and stop at the deadline or on
unmount. No API polling is added.
- Keep timer-driven message rendering separate from large parent pages.
Hidden task-marker details do not subscribe until opened.
- Update task notices, agent run errors in both UI shells, log events,
and provider-limit next actions.
- Update the usage-limit trigger and every window in its popover. Reset
details wrap below the percentage row. The reported timestamp includes
its timezone. Explicit clocks remain fixed for stories.

## Verification

Tested source: `ef79ce40b170db89a6b831162c72d6446cd9492d`. Local checks
ran with the same file contents on macOS arm64, Node 25.6.1, and pnpm
9.15.4.

- From `ui/`: `pnpm exec vitest run
src/lib/provider-limit-message.test.ts src/lib/utils.date-time.test.ts
src/components/ProviderLimitMessage.test.tsx
src/hooks/useSecondTick.test.tsx
src/components/AgentRateLimitGauge.test.tsx
src/components/task-chat/TaskChatMarker.test.tsx
src/components/task-chat/TaskChatSystemNotice.test.tsx
src/components/IssueRunLedger.test.tsx
src/components/IssueRecoveryActionCard.test.tsx
src/components/StalledDependencyNotice.test.tsx
src/pages/AgentDetail.log-visibility.test.tsx
src/pages/AgentDetail.log-resilience.test.tsx` — 176 tests passed across
12 files.
- From `ui/`: `pnpm run typecheck` — passed, including Storybook catalog
generation.
- From the repository root: `pnpm check:token-gates` and `git diff
--check` — passed.
- Regression proof: four live-message cases failed against static
rendering. Four usage-popover cases failed against the old clock. Both
suites passed after the changes.
- Fake-clock tests prove `44 minutes` becomes `43 minutes` without a
page refresh or parent render. Other cases cover seconds near the
deadline, one shared timer, hidden-tab pause and catch-up, expiry, and
cleanup.
- Timezone cases cover Pacific, India, and New Zealand timezones, a
local date rollover, and daylight saving time. Task notice cases cover
both presentations. Usage-popover cases cover Claude and Codex.
- Local setup required a non-frozen install because the base lockfile
lacked two AWS SDK dependencies from the server manifest. No dependency
or lockfile change is included.
- Final CI: [workflow attempt
4](https://github.com/paperclipai/paperclip/actions/runs/44384225521/attempts/4)
succeeded on `ef79ce40b170db89a6b831162c72d6446cd9492d`. All 54
successful checks are green, including the applicable typecheck, build,
server tests, Runner checks, and all eight end-to-end shards. Optional
jobs skipped by the CI plan remain skipped.
- Recovery record: [Canary attempt
1](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135085343566),
[attempt
2](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135097010510),
and [attempt
3](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135100921795)
ended with runner shutdown signals at 19:56:15, 20:12:55, and 20:19:18
UTC. The aggregate verification failures reflected that canary result.
No source changed between attempts. The [fourth Canary Dry
Run](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135105826026)
and [aggregate
verification](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135110708013)
passed.
- Greptile reviewed the final commit at 5/5 with no actionable findings
and no unresolved review threads. GitHub reports the branch mergeable
with a clean merge state.
- Full local repository checks and manual browser acceptance were not
run. CI supplied broad coverage on the final revision. The local popover
tests exercise its content and clock with mocked popover primitives.

## Risks

- Low risk. This changes UI presentation only. No migration or scheduler
change is required.
- The ticker updates visible future countdowns once per second. It makes
no provider request and does not certify that provider capacity has
returned.
- Message recognition uses the existing provider-limit wording and ISO
timestamps. Unrecognized messages retain their text.
- Local timezone abbreviations can differ by browser locale data. Time
conversion uses the browser's timezone rules.

## Model Used

- OpenAI Codex, `gpt-6.1-sol`, with xhigh reasoning effort, repository
inspection, code edits, and test execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs
- [x] I have described the issue in-PR with the enhancement template
fields
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run the focused tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] The code, tests, and this description document the changed output
- [x] I have considered and documented the risks
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-18 14:19:17 -08:00

291 lines
12 KiB
TypeScript

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
import { deriveAgentUrlKey, deriveProjectUrlKey, normalizeProjectUrlKey, hasNonAsciiContent } from "@paperclipai/shared";
import type { BillingType, FinanceDirection, FinanceEventKind } from "@paperclipai/shared";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
export function asObject(value: unknown): Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value)
? value as Record<string, unknown>
: {};
}
export function asBoolean(value: unknown, fallback: boolean) {
return typeof value === "boolean" ? value : fallback;
}
export function asFiniteNumber(value: unknown, fallback: number) {
return typeof value === "number" && Number.isFinite(value) ? value : fallback;
}
export function formatCents(cents: number, currency = "USD"): string {
// Older finance writes accepted arbitrary three-character codes. Keep those
// amounts readable without passing an invalid currency to Intl.
if (!/^[a-z]{3}$/i.test(currency)) {
return `${currency} ${(cents / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
}
return (cents / 100).toLocaleString("en-US", { style: "currency", currency, minimumFractionDigits: 2, maximumFractionDigits: 2 });
}
export function formatNumber(n: number, options?: Intl.NumberFormatOptions): string {
return n.toLocaleString("en-US", options);
}
/**
* Format a project's budget for the projects list view (IA Phase 4 — PAP-60).
* Monthly budgets render a `/mo` suffix; lifetime budgets show the bare amount.
*/
export function formatProjectBudget(budget: { amountCents: number; windowKind: string }): string {
const amount = formatCents(budget.amountCents);
return budget.windowKind === "calendar_month_utc" ? `${amount}/mo` : amount;
}
export function formatDate(date: Date | string): string {
return new Date(date).toLocaleDateString("en-US", {
month: "short",
day: "numeric",
year: "numeric",
});
}
export function formatDateTime(
date: Date | string,
options: { includeSeconds?: boolean; includeYear?: boolean; includeTimeZone?: boolean } = {},
): string {
return new Date(date).toLocaleString("en-US", {
month: "short",
day: "numeric",
...(options.includeYear === false ? {} : { year: "numeric" as const }),
hour: "numeric",
minute: "2-digit",
...(options.includeSeconds ? { second: "2-digit" as const } : {}),
...(options.includeTimeZone ? { timeZoneName: "short" as const } : {}),
});
}
export function formatShortDate(date: Date | string): string {
return new Date(date).toLocaleString("en-US", {
month: "short",
day: "numeric",
});
}
export function relativeTime(date: Date | string): string {
const now = Date.now();
const then = new Date(date).getTime();
const diffSec = Math.round((now - then) / 1000);
if (diffSec < 60) return "just now";
const diffMin = Math.round(diffSec / 60);
if (diffMin < 60) return `${diffMin}m ago`;
const diffHr = Math.round(diffMin / 60);
if (diffHr < 24) return `${diffHr}h ago`;
const diffDay = Math.round(diffHr / 24);
if (diffDay < 30) return `${diffDay}d ago`;
return formatDate(date);
}
export function formatTokens(n: number): string {
if (n >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`;
if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
return String(n);
}
/** Humanize a millisecond duration into a compact `1h 2m`, `45m 12s`, `12s` string. */
export function formatDurationMs(ms: number): string {
if (!Number.isFinite(ms) || ms <= 0) return "0s";
const totalSeconds = Math.round(ms / 1000);
if (totalSeconds < 60) return `${totalSeconds}s`;
const minutes = Math.floor(totalSeconds / 60);
const seconds = totalSeconds % 60;
if (minutes < 60) return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
const hours = Math.floor(minutes / 60);
const remainingMinutes = minutes % 60;
if (hours < 24) {
return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
}
const days = Math.floor(hours / 24);
const remainingHours = hours % 24;
return remainingHours > 0 ? `${days}d ${remainingHours}h` : `${days}d`;
}
/** Map a raw provider slug to a display-friendly name. */
export function providerDisplayName(provider: string): string {
const map: Record<string, string> = {
anthropic: "Anthropic",
aws_bedrock: "AWS Bedrock",
openai: "OpenAI",
openrouter: "OpenRouter",
ollama: "Ollama",
"ollama-cloud": "Ollama Cloud",
chatgpt: "ChatGPT",
google: "Google",
cursor: "Cursor",
jetbrains: "JetBrains AI",
};
return map[provider.toLowerCase()] ?? provider;
}
export function billingTypeDisplayName(billingType: BillingType): string {
const map: Record<BillingType, string> = {
metered_api: "Metered API",
subscription_included: "Subscription",
subscription_overage: "Subscription overage",
credits: "Credits",
fixed: "Fixed",
unknown: "Unknown",
};
return map[billingType];
}
export function quotaSourceDisplayName(source: string): string {
const map: Record<string, string> = {
"anthropic-oauth": "Anthropic OAuth",
"claude-cli": "Claude CLI",
"bedrock": "AWS Bedrock",
"codex-rpc": "Codex app server",
"codex-wham": "ChatGPT WHAM",
};
return map[source] ?? source;
}
function coerceBillingType(value: unknown): BillingType | null {
if (
value === "metered_api" ||
value === "subscription_included" ||
value === "subscription_overage" ||
value === "credits" ||
value === "fixed" ||
value === "unknown"
) {
return value;
}
return null;
}
function readRunCostUsd(payload: Record<string, unknown> | null): number | null {
if (!payload) return null;
for (const key of ["cacheAdjustedCostUsd", "costUsdExact", "costUsd", "cost_usd", "total_cost_usd"] as const) {
const value = payload[key];
if (key === "costUsdExact" && typeof value === "string" && /^\d+(?:\.\d+)?$/.test(value) && Number.isFinite(Number(value))) return Number(value);
if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
}
return null;
}
/** Receipt-backed runs and legacy Claude/Gemini snapshots store uncached input
* separately. OpenCode/Pi persist their provider-qualified model IDs and also
* separate cache reads. Older Codex input already includes cached tokens.
* Unknown legacy formats retain their input-plus-output interpretation. */
export function visibleRunTokenTotal(usage: Record<string, unknown> | null | undefined): number {
const count = (...keys: string[]) => {
for (const key of keys) {
const value = usage?.[key];
if (typeof value === "number" && Number.isFinite(value)) return Math.max(0, value);
}
return 0;
};
const input = count("inputTokens", "input_tokens");
const output = count("outputTokens", "output_tokens");
const cached = count("cachedInputTokens", "cached_input_tokens", "cache_read_input_tokens");
const provider = typeof usage?.provider === "string" ? usage.provider : "";
const model = typeof usage?.model === "string" ? usage.model : "";
// Use the saved model convention, not the agent's current adapter: an agent
// can change adapters after a historical run. Codex saves an unqualified ID.
const qualifiedModel = provider !== "" && provider !== "unknown"
&& model.startsWith(`${provider}/`) && model.length > provider.length + 1;
const inputExcludesCached = usage?.provider === "anthropic"
|| usage?.provider === "google"
|| qualifiedModel
|| (typeof usage?.accountingReceiptId === "string" && usage.accountingReceiptId.length > 0);
return input + output + (inputExcludesCached ? cached : 0);
}
/** Muse exposes Paperclip bridge events, not raw private provider traffic. */
export function supportsRawProviderTrace(adapterType: string, adapterConfig: Record<string, unknown> | null | undefined): boolean {
return adapterType !== "paperclip_runner" || adapterConfig?.provider !== "muse";
}
/** Persisted accounting facts belong to this run, even after its agent changes provider. */
export function hasUnavailableProviderAccounting(result: Record<string, unknown> | null | undefined): boolean {
const accounting = asObject(result?.providerAccounting);
return accounting.externallyBilled === true && accounting.usage === null && accounting.cost === null;
}
export function visibleRunCostUsd(
usage: Record<string, unknown> | null,
result: Record<string, unknown> | null = null,
): number {
const billingType = coerceBillingType(usage?.billingType) ?? coerceBillingType(result?.billingType);
if (billingType === "subscription_included") return 0;
return readRunCostUsd(usage) ?? readRunCostUsd(result) ?? 0;
}
export function financeEventKindDisplayName(eventKind: FinanceEventKind): string {
const map: Record<FinanceEventKind, string> = {
inference_charge: "Inference charge",
platform_fee: "Platform fee",
credit_purchase: "Credit purchase",
credit_refund: "Credit refund",
credit_expiry: "Credit expiry",
byok_fee: "BYOK fee",
gateway_overhead: "Gateway overhead",
log_storage_charge: "Log storage",
logpush_charge: "Logpush",
provisioned_capacity_charge: "Provisioned capacity",
training_charge: "Training",
custom_model_import_charge: "Custom model import",
custom_model_storage_charge: "Custom model storage",
manual_adjustment: "Manual adjustment",
};
return map[eventKind];
}
export function financeDirectionDisplayName(direction: FinanceDirection): string {
return direction === "credit" ? "Credit" : "Debit";
}
/** Build an issue URL using the human-readable identifier when available. */
export function issueUrl(issue: { id: string; identifier?: string | null }): string {
return `/issues/${issue.identifier ?? issue.id}`;
}
/** Build an agent route URL using the short URL key when available. */
export function agentRouteRef(agent: { id: string; urlKey?: string | null; name?: string | null }): string {
return agent.urlKey ?? deriveAgentUrlKey(agent.name, agent.id);
}
/** Build an agent URL using the short URL key when available. */
export function agentUrl(agent: { id: string; urlKey?: string | null; name?: string | null }): string {
return `/agents/${agentRouteRef(agent)}`;
}
/** Build a project route reference, falling back to UUID when the derived key is ambiguous. */
export function projectRouteRef(project: { id: string; urlKey?: string | null; name?: string | null }): string {
const key = project.urlKey ?? deriveProjectUrlKey(project.name, project.id);
// Guard for rolling deploys or legacy data where the server returned a bare slug without UUID suffix.
if (key === normalizeProjectUrlKey(project.name) && hasNonAsciiContent(project.name)) return project.id;
return key;
}
/** Build a project URL using the short URL key when available. */
export function projectUrl(project: { id: string; urlKey?: string | null; name?: string | null }): string {
return `/projects/${projectRouteRef(project)}`;
}
/** Build a project workspace URL scoped under its project. */
export function projectWorkspaceUrl(
project: { id: string; urlKey?: string | null; name?: string | null },
workspaceId: string,
): string {
return `${projectUrl(project)}/workspaces/${workspaceId}`;
}
/** Preserve sub-cent inference charges instead of showing a misleading $0.00. */
export function formatDetailedCents(cents: string | number): string {
return (Number(cents) / 100).toLocaleString("en-US", { style: "currency", currency: "USD", minimumFractionDigits: 2, maximumFractionDigits: 9 });
}