mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
## 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>
291 lines
12 KiB
TypeScript
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 });
|
|
}
|