taskchef 9.3.0 → 9.4.0

package/src/mcp-app/react/UsageView.test.tsx

@@ -0,0 +1,103 @@
+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { afterEach, expect, test, vi } from 'vitest';
+import { UsageView, type UsageData } from './UsageView';
+afterEach(cleanup);
+const data:UsageData={start:'2026-10-01',end:'2026-10-15',timeZone:'Asia/Singapore',samples:2,incomplete:false,totals:{tokens:200,costUsd:3,inputTokens:160,cachedInputTokens:40,outputTokens:40},days:[{date:'2026-10-15',tokens:200,costUsd:3,projects:{a:2,b:1}}],projects:[{id:'a',name:'Alpha',tokens:100,costUsd:2},{id:'b',name:'Beta',tokens:100,costUsd:1}]};
+test('defaults to This month, changes range, isolates projects, and exposes exact day values',async()=>{
+ const request=vi.fn().mockResolvedValue(data);render(<UsageView request={request}/>);
+ await waitFor(()=>expect(screen.getByRole('table')).toBeVisible());
+ expect(request).toHaveBeenCalledWith({range:'mtd',timeZone:expect.any(String)});
+ expect(screen.queryByText(/Custom/)).toBeNull();
+ fireEvent.click(screen.getByRole('button',{name:'7 days'}));
+ await waitFor(()=>expect(request).toHaveBeenLastCalledWith({range:'7d',timeZone:expect.any(String)}));
+ await waitFor(()=>expect(screen.getByRole('table')).toBeVisible());
+ fireEvent.click(screen.getByRole('button',{name:'Alpha'}));
+ expect(screen.getByRole('img',{name:'Daily project cost bars: Alpha'})).toBeVisible();
+ fireEvent.click(screen.getByRole('button',{name:'All projects'}));
+ expect(screen.getByRole('img',{name:'Daily project cost bars: all projects'})).toBeVisible();
+ fireEvent.focus(screen.getByRole('button',{name:'Oct 15: $3.00, 200 tokens'}));
+ expect(screen.getByText('Oct 15 · 200 tokens · $3.00')).toBeVisible();
+});
+test('a late old response cannot replace the selected range and errors can retry',async()=>{
+ let first!:(value:UsageData)=>void;const request=vi.fn().mockImplementationOnce(()=>new Promise<UsageData>(resolve=>{first=resolve;})).mockRejectedValueOnce(new Error('Read failed')).mockResolvedValue(data);
+ render(<UsageView request={request}/>);fireEvent.click(screen.getByRole('button',{name:'90 days'}));
+ expect(await screen.findByRole('alert')).toHaveTextContent('Read failed');
+ first(data);await Promise.resolve();expect(screen.queryByRole('table')).toBeNull();
+ fireEvent.click(screen.getByRole('button',{name:'Retry'}));await waitFor(()=>expect(screen.getByRole('table')).toBeVisible());
+});
+test('missing coverage and empty data are distinct from a zero cost estimate',async()=>{
+ const request=vi.fn().mockResolvedValue({...data,samples:0,incomplete:true});render(<UsageView request={request}/>);
+ await screen.findByText(/No timestamped usage/);expect(screen.queryByText(/Incomplete coverage:/)).toBeNull();expect(screen.queryByRole('table')).toBeNull();
+});
+test('ranks only ten projects and keeps Other out of project identity',async()=>{
+ const projects=Array.from({length:12},(_,i)=>({id:String(i),name:`Project ${i}`,tokens:1,costUsd:12-i}));
+ const request=vi.fn().mockResolvedValue({...data,projects});render(<UsageView request={request}/>);
+ await waitFor(()=>expect(screen.getByRole('table')).toBeVisible());expect(within(screen.getByRole('table')).getAllByRole('row')).toHaveLength(11);expect(screen.getByText('Other')).toBeVisible();
+});
+
+test('polls a pending history read and stops polling when unmounted',async()=>{
+ const request=vi.fn().mockResolvedValueOnce({loading:true}).mockResolvedValue(data);
+ const view=render(<UsageView request={request}/>);expect(await screen.findByRole('status')).toHaveTextContent('Reading saved usage');
+ await waitFor(()=>expect(screen.getByRole('table')).toBeVisible(),{timeout:2000});
+ expect(request).toHaveBeenLastCalledWith({range:'mtd',timeZone:expect.any(String)});
+ view.unmount();
+ const pending=vi.fn().mockResolvedValue({loading:true});const second=render(<UsageView request={pending}/>);await waitFor(()=>expect(pending).toHaveBeenCalledTimes(1));second.unmount();
+});
+
+test('a hidden view does not start historical usage reads',async()=>{
+ const visibility=vi.spyOn(document,'visibilityState','get').mockReturnValue('hidden');
+ try {const request=vi.fn().mockResolvedValue(data);render(<UsageView request={request}/>);expect(request).not.toHaveBeenCalled();visibility.mockReturnValue('visible');await waitFor(()=>expect(screen.getByRole('table')).toBeVisible(),{timeout:2000});expect(request).toHaveBeenCalledTimes(1);}
+ finally{visibility.mockRestore();}
+});
+
+test('Last month follows This month and range changes reuse history without forcing a scan',async()=>{
+ const request=vi.fn().mockResolvedValue(data);render(<UsageView request={request}/>);
+ await waitFor(()=>expect(screen.getByRole('table')).toBeVisible());
+ const buttons=within(screen.getByRole('group',{name:'Usage time range'})).getAllByRole('button');
+ expect(buttons.map(button=>button.textContent)).toEqual(['7 days','30 days','90 days','This month','Last month']);
+ fireEvent.click(screen.getByRole('button',{name:'Last month'}));await waitFor(()=>expect(request).toHaveBeenLastCalledWith({range:'last-month',timeZone:expect.any(String)}));
+ fireEvent.click(screen.getByRole('button',{name:'This month'}));await waitFor(()=>expect(request).toHaveBeenCalledTimes(3));expect(request.mock.calls.every(([args])=>!args.force)).toBe(true);
+});
+test('Refresh forces one new read and shows measured progress while cached data stays visible',async()=>{
+ const request=vi.fn().mockResolvedValueOnce(data).mockResolvedValueOnce({...data,refreshing:true,progress:{completed:2,total:10}}).mockResolvedValue(data);
+ const view=render(<UsageView request={request}/>);await waitFor(()=>expect(screen.getByRole('table')).toBeVisible());
+ view.rerender(<UsageView request={request} refreshKey={1}/>);
+ await screen.findByText('Updating saved usage… 2 of 10 chats');expect(screen.getByRole('progressbar',{name:'Usage scan progress'})).toHaveAttribute('value','2');expect(screen.getByRole('table')).toBeVisible();
+ expect(request).toHaveBeenLastCalledWith({range:'mtd',timeZone:expect.any(String),force:true});await waitFor(()=>expect(screen.queryByRole('progressbar')).toBeNull());
+});
+test('legend hover and focus highlight only matching project bars and reset on leave',async()=>{
+ const request=vi.fn().mockResolvedValue(data);const view=render(<UsageView request={request}/>);await waitFor(()=>expect(screen.getByRole('table')).toBeVisible());
+ const alpha=screen.getByRole('button',{name:'Alpha'});fireEvent.mouseEnter(alpha);
+ expect(view.container.querySelector('[data-project="a"]')).toHaveAttribute('opacity','1');expect(view.container.querySelector('[data-project="b"]')).toHaveAttribute('opacity','0.2');
+ fireEvent.mouseLeave(alpha);expect(view.container.querySelector('[data-project="b"]')).toHaveAttribute('opacity','1');
+ fireEvent.focus(alpha);expect(view.container.querySelector('[data-project="b"]')).toHaveAttribute('opacity','0.2');fireEvent.blur(alpha);expect(view.container.querySelector('[data-project="b"]')).toHaveAttribute('opacity','1');
+});
+
+ test('Rescan rebuilds explicitly and removes coverage and axis helper copy',async()=>{
+ const request=vi.fn().mockResolvedValue({...data,incomplete:true});render(<UsageView request={request}/>);
+ await screen.findByRole('table');
+ for(const text of [/Incomplete coverage/,/Known subtotal/,/Cached input is included/,/right axis/,/left axis/,/By estimated cost/,/Missing usage is not zero/]) expect(screen.queryByText(text)).toBeNull();
+ fireEvent.click(screen.getByRole('button',{name:'Rescan'}));
+ await waitFor(()=>expect(request).toHaveBeenLastCalledWith({range:'mtd',timeZone:expect.any(String),rescan:true}));
+ });
+
+test('only the current local day has dashed bars and token segment; a completed period stays solid',async()=>{
+ vi.useFakeTimers({toFake:['Date']});vi.setSystemTime(new Date('2026-10-15T17:00:00Z'));
+ try {
+  const days=[{...data.days[0],date:'2026-10-15'},{...data.days[0],date:'2026-10-16'}];
+  const request=vi.fn().mockResolvedValueOnce({...data,end:'2026-10-16',days}).mockResolvedValue({...data,start:'2026-09-01',end:'2026-09-30',days:[{...data.days[0],date:'2026-09-30'}]});
+  render(<UsageView request={request}/>);await screen.findByRole('table');
+  const combined=screen.getByRole('img',{name:'Daily estimated cost bars and token line'});
+  expect(combined.querySelectorAll('rect[stroke-dasharray]')).toHaveLength(1);
+  expect(combined.querySelectorAll('polyline[stroke-dasharray]')).toHaveLength(1);
+  expect(screen.getByRole('button',{name:/Oct 16: .*in progress/})).toBeVisible();
+  const projects=screen.getByRole('img',{name:'Daily project cost bars: all projects'});
+  expect(projects.querySelectorAll('rect[stroke-dasharray]')).toHaveLength(2);
+  fireEvent.click(screen.getByRole('button',{name:'Alpha'}));
+  expect(screen.getByRole('img',{name:'Daily project cost bars: Alpha'}).querySelectorAll('rect[stroke-dasharray]')).toHaveLength(1);
+  fireEvent.click(screen.getByRole('button',{name:'Last month'}));
+  await waitFor(()=>expect(screen.getByText(/Sep 1 – Sep 30/)).toBeVisible());
+  expect(screen.getByRole('img',{name:'Daily estimated cost bars and token line'}).querySelectorAll('[stroke-dasharray]')).toHaveLength(0);
+  expect(screen.getByRole('img',{name:'Daily project cost bars: Alpha'}).querySelectorAll('[stroke-dasharray]')).toHaveLength(0);
+ } finally {vi.useRealTimers();}
+});

package/src/mcp-app/react/UsageView.tsx

@@ -0,0 +1,128 @@
+import { useEffect, useRef, useState } from "react";
+
+export interface UsageData {
+  updatedAt?: string; refreshing?: boolean; progress?: ScanProgress;
+  start: string; end: string; timeZone: string; samples: number; incomplete: boolean;
+  totals: { tokens: number; costUsd: number; inputTokens: number; cachedInputTokens: number; outputTokens: number };
+  days: { date: string; tokens: number; costUsd: number; projects: Record<string, number> }[];
+  projects: { id: string; name: string; costUsd: number; tokens: number }[];
+}
+interface ScanProgress { completed: number; total: number; }
+export type UsageRange = "7d" | "30d" | "90d" | "mtd" | "last-month";
+export const usageRequest = (range: UsageRange, force = false, rescan = false) => ({ range, timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone, ...(force ? { force: true } : {}), ...(rescan ? { rescan: true } : {}) });
+export type UsageResponse = UsageData | { loading: true; progress?: ScanProgress };
+const money = (n: number) => new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", maximumFractionDigits: n > 0 && n < .01 ? 4 : 2 }).format(n);
+const count = (n: number) => new Intl.NumberFormat("en", { notation: "compact", maximumFractionDigits: 1 }).format(n);
+const dateLabel = (value: string) => new Date(`${value}T12:00:00Z`).toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: "UTC" });
+const colors = ["#6e91ad", "#80ad99", "#b8a0ca", "#c2a06e", "#c78585", "#92979c"];
+const left = 64, right = 794, top = 16, bottom = 166;
+
+export function UsageView({ request, refreshKey = 0 }: { request: (args: ReturnType<typeof usageRequest>) => Promise<UsageResponse>; refreshKey?: number }) {
+  const [range, setRange] = useState<UsageRange>("mtd");
+  const [data, setData] = useState<UsageData | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [progress, setProgress] = useState<ScanProgress | null>(null);
+  const [highlighted, setHighlighted] = useState<string | null>(null);
+  const lastRequest = useRef({ refreshKey, retry: 0, rescan: 0 });
+  const [selected, setSelected] = useState<string | null>(null);
+  const [activeDay, setActiveDay] = useState<number | null>(null);
+  const [retry, setRetry] = useState(0);
+  const [rescan, setRescan] = useState(0);
+  useEffect(() => {
+    let current = true;
+    const force = refreshKey !== lastRequest.current.refreshKey || retry !== lastRequest.current.retry;
+    const rebuild = rescan !== lastRequest.current.rescan;
+    lastRequest.current = { refreshKey, retry, rescan };
+    setLoading(true); setError(null); setProgress(null); setActiveDay(null); setHighlighted(null);
+    if (!force && !rebuild) setData(null);
+    let timer: ReturnType<typeof setTimeout>;
+    async function load(force: boolean, rebuild = false) {
+      if (document.visibilityState === "hidden") { timer = setTimeout(() => { void load(force, rebuild); }, 1000); return; }
+      try {
+        const result = await request(usageRequest(range, force, rebuild));
+        if (!current) return;
+        setProgress(result.progress ?? null);
+        if ("loading" in result) timer = setTimeout(() => { void load(false); }, 250);
+        else {
+          setData(result); setLoading(false);
+          if (result.refreshing) timer = setTimeout(() => { void load(false); }, 250);
+        }
+      } catch (cause) { if (current) { setError(String(cause)); setLoading(false); } }
+    }
+    void load(force, rebuild);
+    return () => { current = false; clearTimeout(timer); };
+  }, [range, request, refreshKey, retry, rescan]);
+  const today = data ? new Intl.DateTimeFormat("en-CA", { timeZone: data.timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).format(new Date()) : "";
+  const unfinished = (date: string) => date === today;
+  const barStyle = (date: string, color: string) => unfinished(date) ? { fillOpacity: .35, stroke: color, strokeWidth: 1.5, strokeDasharray: "4 3" } : {};
+  const project = data?.projects.find(item => item.id === selected);
+  const series = data ? (project ? [{ ...project, color: colors[data.projects.indexOf(project) < 5 ? data.projects.indexOf(project) : 5] }]
+    : [...data.projects.slice(0, 5).map((item, index) => ({ ...item, color: colors[index] })),
+      ...(data.projects.length > 5 ? [{ id: "__other", name: "Other", costUsd: 0, tokens: 0, color: colors[5] }] : [])]) : [];
+  const activeHighlight = series.some(item => item.id === highlighted) ? highlighted : null;
+  const dayWidth = data ? (right - left) / data.days.length : 1;
+  const maxCost = Math.max(...(data?.days.map(day => day.costUsd) ?? []), .01);
+  const maxTokens = Math.max(...(data?.days.map(day => day.tokens) ?? []), 1);
+  const projectCost = (day: UsageData["days"][number], id: string) => id === "__other"
+    ? data!.projects.slice(5).reduce((sum, item) => sum + (day.projects[item.id] ?? 0), 0) : day.projects[id] ?? 0;
+  const maxProjectCost = Math.max(...(data?.days.map(day => series.reduce((sum, item) => sum + projectCost(day, item.id), 0)) ?? []), .01);
+  const x = (index: number) => left + (index + .5) * dayWidth;
+  const y = (value: number, max: number) => bottom - value / max * (bottom - top);
+  function grid(max: number, tokens = false) {
+    return [0, .5, 1].map(fraction => <g key={fraction}>
+      <line x1={left} x2={right} y1={y(fraction, 1)} y2={y(fraction, 1)} className="usage-grid" />
+      <text x={left - 10} y={y(fraction, 1) + 4} textAnchor="end">{tokens ? count(max * fraction) : money(max * fraction)}</text>
+    </g>);
+  }
+  function dates() {
+    return data!.days.map((day, index) => index === 0 || index === data!.days.length - 1 || index % Math.ceil(data!.days.length / 5) === 0
+      ? <text key={day.date} x={x(index)} y={bottom + 25} textAnchor="middle">{dateLabel(day.date)}</text> : null);
+  }
+  return <section className="usage-view" aria-label="Usage analytics">
+    <div className="usage-heading"><div><h2>Usage</h2><p>Tokens and estimated cost across your Codex work.</p></div><button disabled={loading || data?.refreshing} onClick={() => setRescan(value => value + 1)}>Rescan</button></div>
+    <div className="usage-ranges" role="group" aria-label="Usage time range">
+      {([ ["7d", "7 days"], ["30d", "30 days"], ["90d", "90 days"], ["mtd", "This month"], ["last-month", "Last month"] ] as const).map(([value, label]) => <button key={value} aria-pressed={range === value} onClick={() => setRange(value)}>{label}</button>)}
+    </div>
+    {(loading || data?.refreshing) && !error && <div className="usage-progress" role="status">
+      <p>{data ? "Updating saved usage…" : "Reading saved usage…"} {progress?.total ? `${progress.completed} of ${progress.total} chats` : "Preparing history…"}</p>
+      <progress aria-label="Usage scan progress" max={progress?.total || 1} value={progress?.total ? progress.completed : undefined} />
+    </div>}
+    {error && <div role="alert"><p>Usage could not be loaded: {error}</p><button onClick={() => setRetry(value => value + 1)}>Retry</button></div>}
+    {data && <>
+      <p className="usage-period">{dateLabel(data.start)} – {dateLabel(data.end)} · {data.timeZone} · Daily · Includes archived chats and subagent usage{data.updatedAt && <> · Updated {new Date(data.updatedAt).toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" })}</>}</p>
+      {!data.samples ? <p role="status">No timestamped usage is available for this period.</p> : <>
+        <div className="usage-totals">
+          <article><h3>Recorded tokens</h3><strong>{count(data.totals.tokens)}</strong><p>Input {count(data.totals.inputTokens)} · Cached input {count(data.totals.cachedInputTokens)} · Output {count(data.totals.outputTokens)}</p></article>
+          <article><h3>Estimated cost</h3><strong>{money(data.totals.costUsd)}</strong><p>API-equivalent prices · USD</p></article>
+        </div>
+        <article className="usage-panel" aria-label="Tokens and cost over time"><h3>Tokens and cost over time</h3>
+          <div className="usage-legend"><span className="usage-token-key">━ Tokens</span><span><i style={{ background: colors[0] }} /> Estimated cost</span></div>
+          <div className="usage-chart-scroll"><svg viewBox="0 0 860 210" role="img" aria-label="Daily estimated cost bars and token line" className="usage-chart">
+            {grid(maxCost)}
+            {[0, .5, 1].map(fraction => <text className="usage-token-axis" key={fraction} x={right + 10} y={y(fraction, 1) + 4}>{count(maxTokens * fraction)}</text>)}
+            {data.days.map((day, index) => <rect key={day.date} x={x(index) - dayWidth * .3} y={y(day.costUsd, maxCost)} width={dayWidth * .6} height={bottom - y(day.costUsd, maxCost)} fill={colors[0]} {...barStyle(day.date, colors[0])}><title>{dateLabel(day.date)}{unfinished(day.date) ? " (in progress)" : ""}: {money(day.costUsd)}, {day.tokens.toLocaleString()} tokens</title></rect>)}
+            <polyline className="usage-token-line" points={data.days.map((day, index) => unfinished(day.date) ? null : `${x(index)},${y(day.tokens, maxTokens)}`).filter(Boolean).join(" ")} />
+            {data.days.map((day, index) => unfinished(day.date) && index > 0 ? <polyline key={day.date} className="usage-token-line" strokeDasharray="5 4" points={`${x(index - 1)},${y(data.days[index - 1].tokens, maxTokens)} ${x(index)},${y(day.tokens, maxTokens)}`} /> : null)}
+            {data.days.map((day, index) => <g key={day.date} tabIndex={0} role="button" aria-label={`${dateLabel(day.date)}: ${money(day.costUsd)}, ${day.tokens.toLocaleString()} tokens${unfinished(day.date) ? " (in progress)" : ""}`} onMouseEnter={() => setActiveDay(index)} onFocus={() => setActiveDay(index)} onClick={() => setActiveDay(index)} onKeyDown={event => { if (event.key === "Enter" || event.key === " ") { event.preventDefault(); setActiveDay(index); } }}><rect x={left + index * dayWidth} y={top} width={dayWidth} height={bottom - top} fill="transparent" /><circle cx={x(index)} cy={y(day.tokens, maxTokens)} r={data.days.length > 30 ? 0 : 2.5} className="usage-token-dot" /></g>)}
+            {dates()}
+          </svg></div>
+          <p className="usage-chart-detail" aria-live="polite">{activeDay === null ? "Hover or focus a day to inspect its usage." : `${dateLabel(data.days[activeDay].date)} · ${data.days[activeDay].tokens.toLocaleString()} tokens · ${money(data.days[activeDay].costUsd)}`}</p>
+        </article>
+        <article className="usage-panel" aria-label="Cost by project over time"><h3>Cost by project over time</h3>
+          <p>{project ? `${project.name} · ` : "Top 5 projects + Other · "}Select a project below to isolate its cost.</p>
+          <div className="usage-legend"><button aria-pressed={!project} onMouseEnter={() => setHighlighted(null)} onFocus={() => setHighlighted(null)} onClick={() => setSelected(null)}>All projects</button>{data.projects.slice(0, 5).map((item, index) => <button key={item.id} aria-pressed={project?.id === item.id} onMouseEnter={() => setHighlighted(item.id)} onMouseLeave={() => setHighlighted(null)} onFocus={() => setHighlighted(item.id)} onBlur={() => setHighlighted(null)} onClick={() => setSelected(project?.id === item.id ? null : item.id)}><i style={{ background: colors[index] }} />{item.name}</button>)}{data.projects.length > 5 && <span tabIndex={0} onMouseEnter={() => setHighlighted("__other")} onMouseLeave={() => setHighlighted(null)} onFocus={() => setHighlighted("__other")} onBlur={() => setHighlighted(null)}><i style={{ background: colors[5] }} />Other</span>}</div>
+          <div className="usage-chart-scroll"><svg viewBox="0 0 860 210" role="img" aria-label={`Daily project cost bars: ${project?.name ?? "all projects"}`} className="usage-chart">
+            {grid(maxProjectCost)}
+            {data.days.map((day, index) => { let accumulated = 0; return <g key={day.date}>{series.map(item => { const cost = projectCost(day, item.id); const start = accumulated; accumulated += cost; return <rect key={item.id} x={x(index) - dayWidth * .3} y={y(accumulated, maxProjectCost)} width={dayWidth * .6} height={(cost / maxProjectCost) * (bottom - top)} fill={item.color} {...barStyle(day.date, item.color)} data-project={item.id} opacity={activeHighlight && activeHighlight !== item.id ? .2 : 1}><title>{dateLabel(day.date)}{unfinished(day.date) ? " (in progress)" : ""} · {item.name}: {money(accumulated - start)}</title></rect>; })}</g>; })}
+            {dates()}
+          </svg></div>
+        </article>
+        <article className="usage-panel" aria-label="Top 10 projects"><h3>Top 10 projects</h3>
+          <div className="usage-ranking"><table><thead><tr><th scope="col">Project</th><th scope="col">Estimated cost</th><th scope="col">Share</th></tr></thead><tbody>{data.projects.slice(0, 10).map((item, index) => <tr key={item.id}><th scope="row"><button aria-pressed={project?.id === item.id} onClick={() => setSelected(project?.id === item.id ? null : item.id)}><span>{index + 1}. {item.name}</span><span className="usage-rank-track" aria-hidden><span style={{ width: `${data.projects[0].costUsd ? item.costUsd / data.projects[0].costUsd * 100 : 0}%`, background: colors[index < 5 ? index : 5] }} /></span></button></th><td>{money(item.costUsd)}</td><td>{data.totals.costUsd ? (item.costUsd / data.totals.costUsd * 100).toFixed(1) : "0.0"}%</td></tr>)}</tbody></table></div>
+        </article>
+      </>}
+      <p className="usage-footnote">Cost is estimated at API-equivalent prices, not your subscription bill or remaining allowance.</p>
+    </>}
+  </section>;
+}

package/src/mcp-app/react/main.test.tsx

@@ -118,13 +118,14 @@ test("lifecycle events log readable single strings without suppressing repeats",
   expect(warn).not.toHaveBeenCalled();
 });
 
-test("shows only Board, ignores a saved List choice, and filters project and date", async () => {
+test("defaults to Board, ignores a saved List choice, and filters project and date", async () => {
   window.localStorage.setItem("taskchef.app.view", "list");
   tasks = [task("one", "working", new Date().toISOString(), "Alpha"), task("two", "completed", "2026-01-01T00:00:00Z", "Alpha"), task("three", "interrupted", new Date().toISOString(), "Beta")];
   mount();
   await screen.findByRole("button", { name: "Task one" });
   expect(screen.getByRole("region", { name: "Task board" })).toBeVisible();
-  expect(screen.queryByRole("radiogroup", { name: "View" })).not.toBeInTheDocument();
+  expect(screen.getByRole("radio", { name: "Board" })).toHaveAttribute("aria-checked", "true");
+  expect(screen.queryByRole("radio", { name: "List" })).not.toBeInTheDocument();
   expect(screen.queryByRole("radiogroup", { name: "Status" })).not.toBeInTheDocument();
   fireEvent.change(screen.getByRole("combobox", { name: "Project" }), { target: { value: "/Alpha" } });
   expect(screen.queryByRole("button", { name: "Task three" })).not.toBeInTheDocument();
@@ -667,3 +668,16 @@ test("Pinned toggle combines with filters and updates after pin changes on refre
   expect(toggle).toHaveAttribute("aria-pressed", "false");
   expect(screen.getByRole("button", { name: "Task two" })).toBeVisible();
 });
+
+
+test("Usage opens on demand and returns to Board without keeping its filters visible", async () => {
+  const original = server.call.getMockImplementation()!;
+  server.call.mockImplementation((input) => input.name === "taskchef_app_usage" ? Promise.resolve({structuredContent:{start:"2026-10-01",end:"2026-10-15",timeZone:"UTC",days:[],projects:[],totals:{},samples:0,incomplete:false}}) : original(input));
+  mount();await screen.findByRole("button",{name:"Task one"});
+  expect(server.call.mock.calls.some(([input])=>input.name === "taskchef_app_usage")).toBe(false);
+  fireEvent.click(screen.getByRole("radio",{name:"Usage"}));
+  await screen.findByText("No timestamped usage is available for this period.");
+  expect(screen.queryByRole("combobox",{name:"Project"})).toBeNull();
+  fireEvent.click(screen.getByRole("radio",{name:"Board"}));
+  expect(screen.getByRole("region",{name:"Task board"})).toBeVisible();
+});

package/src/mcp-app/react/main.tsx

@@ -14,6 +14,7 @@ import { NextNotificationCenter, type NextNotification, type NextNotificationSta
 import { GitHubConnection, type GitHubAuth } from "./GitHubConnection";
 import { AppearancePicker } from "./AppearancePicker";
 import { savedVisualTheme, themeVariables, visualTheme, VISUAL_THEME_KEY } from "./themes";
+import { UsageView, type UsageResponse, type usageRequest } from "./UsageView";
 import { ProjectPicker } from "./ProjectPicker";
 import brandIcon from "../../../assets/taskchef-dark.svg";
 import "@mantine/core/styles.css";
@@ -40,6 +41,8 @@ async function call<T>(name: string, args: Record<string, unknown> = {}): Promis
   return result.structuredContent as T;
 }
 
+const readUsage = (args: ReturnType<typeof usageRequest>) => call<UsageResponse>("taskchef_app_usage", args);
+
 const THEME_KEY = "taskchef.app.theme";
 type ThemeChoice = "dark" | "light" | "system";
 function initialTheme(): ThemeChoice {
@@ -159,8 +162,9 @@ export function TaskChefApp() {
   const [search, setSearch] = useState("");
   const [date, setDate] = useState("all");
   const [status, setStatus] = useState("");
-  // Keep the list implementation for later, but expose only Board. Ignore old saved List choices.
-  const [view, setView] = useState<"board" | "list">("board");
+  // Keep the legacy list hidden; Board and Usage share the native shell.
+  const [view, setView] = useState<"board" | "list" | "usage">("board");
+  const [usageRefreshKey, setUsageRefreshKey] = useState(0);
   const [completedLimit, setCompletedLimit] = useState(5);
   const [archivedLimit, setArchivedLimit] = useState(5);
   const [now, setNow] = useState(() => Date.now());
@@ -420,7 +424,8 @@ export function TaskChefApp() {
       <Box className={`taskchef-app-shell${displayMode === "inline" ? " taskchef-app-inline" : ""}`}>
         <header className="taskchef-app-header">
           <Group className="taskchef-app-brand" gap="xs" wrap="nowrap"><img alt="" aria-hidden className="taskchef-app-mark" src={brandIcon} /><Title order={1}>TaskChef</Title></Group>
-          {displayMode !== "inline" && <Group className="taskchef-app-filters" gap="xs" wrap="wrap">
+          {displayMode !== "inline" && <SegmentedControl className="taskchef-app-view" aria-label="View" data={[{ label: "Board", value: "board" }, { label: "Usage", value: "usage" }]} value={view} onChange={value => setView(value === "usage" ? "usage" : "board")} size="xs" />}
+          {displayMode !== "inline" && view !== "usage" && <Group className="taskchef-app-filters" gap="xs" wrap="wrap">
             <ProjectPicker data={projects} onChange={(value) => { setProject(value); setCompletedLimit(5); }} value={project} />
             <Select className="taskchef-app-date" aria-label="Updated" data={[{ label: "Latest 24 hours", value: "24h" }, { label: "Latest 7 days", value: "7d" }, { label: "All time", value: "all" }]} onChange={(value) => { setDate(value ?? "all"); setCompletedLimit(5); }} value={date} size="xs" />
             <TextInput className="taskchef-app-search" aria-label="Search Chats" placeholder="Search Chats" type="search" leftSection={<IconSearch size={14} aria-hidden />} value={search} onChange={(event) => { setSearch(event.currentTarget.value); setCompletedLimit(5); setArchivedLimit(5); }} size="xs" />
@@ -433,7 +438,7 @@ export function TaskChefApp() {
             try { await call("taskchef_app_open_settings", {}); }
             catch (cause) { await actionError("settings", cause); }
           })()} variant="subtle"><IconSettings size={17} /></ActionIcon>
-          <ActionIcon aria-label="Refresh" onClick={() => void refresh(true).catch((cause) => setError(String(cause)))} variant="subtle"><IconRefresh size={17} /></ActionIcon>
+          <ActionIcon aria-label="Refresh" onClick={() => { setUsageRefreshKey(value => value + 1); void refresh(true).catch((cause) => setError(String(cause))); }} variant="subtle"><IconRefresh size={17} /></ActionIcon>
           <AppearancePicker value={themeChoice} onChange={chooseTheme} visualThemeId={selectedTheme.id} appearance={colorScheme} onVisualThemeChange={chooseVisualTheme} />
           </Group>
         </header>
@@ -449,6 +454,7 @@ export function TaskChefApp() {
           {view === "list" && <Paper className="taskchef-toolbar" radius={0}>
             <Box className="taskchef-app-status"><SegmentedControl aria-label="Status" data={statusOptions} onChange={setStatus} size="xs" value={status} withItemsBorders={false} /></Box>
           </Paper>}
+          {view === "usage" ? <UsageView key={`${showCli}:${showExec}`} request={readUsage} refreshKey={usageRefreshKey} /> : <>
           {!!scan?.scheduleErrors && <Alert color="yellow" role="alert">{scan.scheduleErrors} schedule files could not be read; schedule placement may be incomplete.</Alert>}
           {view === "list" && <Text aria-live="polite" className="taskchef-results-summary" id="task-results-summary">Tasks: {visible.length} of {eligibleTasks.length}</Text>}
           {error && <Alert color="red" role="alert" mt="sm">{error}</Alert>}
@@ -457,6 +463,7 @@ export function TaskChefApp() {
               {visible.map((task) => <TaskCard key={task.id} onOpenCodex={(item) => void openChat(item)} onOpenDetail={(item) => void select(item)} task={task} />)}
               {visible.length === 0 && <Paper className="taskchef-empty" p="lg" ta="center" withBorder><Title order={2} size="h5">No tasks match these filters</Title><Text c="dimmed" size="sm">Choose a different project, update window, or status.</Text></Paper>}
             </Stack>)}
+          </>}
         </main>
         </>}
         {taskchefVersion && displayMode !== "inline" && <footer className="taskchef-app-version" aria-label="TaskChef version">v{taskchefVersion}</footer>}

package/src/mcp-app/react/styles.css

@@ -15,7 +15,7 @@
 html, body, #root { min-width: 0; min-height: 100%; }
 body { background: var(--taskchef-page); }
 .taskchef-app-shell { min-height: 100vh; background: var(--taskchef-page); }
-.taskchef-app-header { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; grid-template-areas: "brand filters actions"; align-items: center; gap: 12px; padding: 12px 14px; border-bottom: 1px solid var(--taskchef-border); }
+.taskchef-app-header { display: grid; grid-template-columns: auto auto minmax(0, 1fr) auto; grid-template-areas: "brand view filters actions"; align-items: center; gap: 12px; padding: 12px 14px; border-bottom: 1px solid var(--taskchef-border); }
 .taskchef-app-brand { grid-area: brand; }
 .taskchef-app-actions { grid-area: actions; }
 .taskchef-app-header h1 { color: var(--taskchef-text); font-size: 14px; font-weight: 600; line-height: 1.4; white-space: nowrap; }
@@ -26,14 +26,18 @@ body { background: var(--taskchef-page); }
 .taskchef-app-main-list { max-width: 624px; margin-inline: auto; }
 .taskchef-app-main .taskchef-toolbar { margin-bottom: 8px; padding-bottom: 10px; }
 .taskchef-app-main .mantine-SegmentedControl-root { max-width: 100%; }
-.taskchef-app-view { width: max-content; }
-.taskchef-app-filters { grid-area: filters; min-width: 0; width: min(100%, 680px); }
+.taskchef-app-view { grid-area: view; width: max-content; }
+.taskchef-app-filters { grid-area: filters; border-inline-start: 1px solid var(--taskchef-border); padding-inline-start: 12px; min-width: 0; width: min(100%, 680px); }
 .taskchef-app-filters .mantine-InputWrapper-root { flex: 1 1 100px; min-width: 100px; }
 .taskchef-app-pinned { flex: 0 0 auto; white-space: nowrap; }
 .taskchef-app-filters .taskchef-app-date { flex: 0 0 132px; }
-@media (max-width: 650px) {
-  .taskchef-app-header { grid-template-columns: minmax(0, 1fr) auto; grid-template-areas: "brand actions" "filters filters"; gap: 8px; }
-  .taskchef-app-filters { width: 100%; }
+@media (max-width: 1000px) {
+  .taskchef-app-header { grid-template-columns: auto minmax(0, 1fr) auto; grid-template-areas: "brand view actions" "filters filters filters"; gap: 8px; }
+  .taskchef-app-filters { width: 100%; border-inline-start: 0; padding-inline-start: 0; border-top: 1px solid var(--taskchef-border); padding-top: 8px; }
+}
+@media (max-width: 500px) {
+  .taskchef-app-header { grid-template-columns: auto minmax(0, 1fr); grid-template-areas: "brand view" "actions actions" "filters filters"; }
+  .taskchef-app-actions { justify-self: end; }
 }
 .taskchef-app-status { max-width: 100%; overflow-x: auto; scrollbar-width: thin; }
 .taskchef-app-status .mantine-SegmentedControl-root { width: max-content; min-width: max-content; }
@@ -107,7 +111,7 @@ body { background: var(--taskchef-page); }
 .taskchef-reply-cover { background: var(--taskchef-page); }
 
 @media (max-width: 380px) {
-  .taskchef-app-header { grid-template-areas: "brand brand" "actions actions" "filters filters"; }
+  .taskchef-app-header { grid-template-areas: "brand view" "actions actions" "filters filters"; }
   .taskchef-app-inline .taskchef-app-header { grid-template-areas: "brand brand" "actions actions"; }
   .taskchef-app-actions { justify-self: end; }
 }
@@ -221,3 +225,46 @@ body { background: var(--taskchef-page); }
 .taskchef-turn-error-compact { gap: 6px; margin-top: 8px; padding: 0; border: 0; border-radius: 0; background: transparent; font-size: var(--mantine-font-size-xs); }
 
 .taskchef-turn-error-compact > span { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden; }
+
+.usage-view { max-width: 1100px; margin: 0 auto; color: var(--taskchef-text); }
+.usage-heading { display: flex; justify-content: space-between; align-items: center; gap: 12px; }
+.usage-view button:disabled { opacity: .5; cursor: default; }
+.usage-view h2 { font-size: 24px; margin: 4px 0 8px; }
+.usage-view h3 { font-size: 14px; margin: 0 0 12px; }
+.usage-view p, .usage-view small { color: var(--taskchef-muted); font-size: 12px; line-height: 1.5; margin: 8px 0; }
+.usage-ranges, .usage-legend { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin: 16px 0; }
+.usage-view button { font: inherit; font-size: 12px; color: var(--taskchef-text); background: transparent; border: 1px solid var(--taskchef-border); border-radius: 6px; padding: 6px 10px; cursor: pointer; }
+.usage-view button:hover, .usage-view button[aria-pressed="true"] { background: var(--taskchef-hover); border-color: var(--taskchef-muted); }
+.usage-view button:focus-visible, .usage-chart g:focus-visible { outline: 2px solid var(--taskchef-focus); outline-offset: 2px; }
+.usage-totals { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px; margin: 16px 0; }
+.usage-totals article, .usage-panel { padding: 18px; border: 1px solid var(--taskchef-border); border-radius: 10px; background: var(--taskchef-surface); min-width: 0; }
+.usage-totals strong { font-size: 28px; font-weight: 600; }
+.usage-panel { margin: 16px 0; }
+.usage-legend { font-size: 12px; gap: 12px; }
+.usage-legend span, .usage-legend button { display: inline-flex; align-items: center; gap: 6px; }
+.usage-legend i { display: inline-block; width: 10px; height: 10px; border-radius: 2px; flex-shrink: 0; }
+.usage-legend button { max-width: 100%; overflow-wrap: anywhere; text-align: left; }
+.usage-token-key, .usage-chart .usage-token-axis { color: light-dark(#a54d2e, #efb18b); fill: light-dark(#a54d2e, #efb18b); }
+.usage-token-line { stroke: light-dark(#a54d2e, #efb18b); stroke-width: 2.5; fill: none; pointer-events: none; }
+.usage-token-dot { fill: light-dark(#a54d2e, #efb18b); pointer-events: none; }
+.usage-chart-scroll { overflow-x: auto; }
+.usage-chart { width: 100%; min-width: 500px; display: block; font: 11px var(--taskchef-font, sans-serif); fill: var(--taskchef-muted); }
+.usage-grid { stroke: var(--taskchef-border); }
+.usage-chart-detail { min-height: 18px; }
+.usage-ranking { overflow-x: auto; }
+.usage-ranking table { width: 100%; border-collapse: collapse; font-size: 12px; }
+.usage-ranking th, .usage-ranking td { padding: 6px; text-align: right; font-weight: normal; }
+.usage-ranking th:first-child { width: 70%; text-align: left; }
+.usage-ranking td { white-space: nowrap; font-variant-numeric: tabular-nums; }
+.usage-ranking thead { color: var(--taskchef-muted); }
+.usage-ranking button { width: 100%; display: flex; align-items: center; gap: 12px; border-color: transparent; text-align: left; }
+.usage-ranking button > span:first-child { width: 45%; overflow-wrap: anywhere; }
+.usage-rank-track { flex: 1; height: 8px; border-radius: 2px; background: var(--taskchef-border); overflow: hidden; }
+.usage-rank-track > span { display: block; height: 100%; }
+.usage-warning { padding: 10px; border: 1px solid var(--taskchef-border); border-radius: 6px; }
+@media (max-width: 500px) { .usage-totals { grid-template-columns: 1fr; gap: 10px; } .usage-panel { padding: 12px; } .usage-rank-track { display: none; } .usage-ranking button > span:first-child { width: 100%; } }
+
+.usage-progress { margin: 16px 0; }
+.usage-progress progress { display: block; width: 100%; height: 6px; accent-color: var(--taskchef-accent); }
+.usage-chart [data-project] { transition: opacity 120ms ease; }
+@media (prefers-reduced-motion: reduce) { .usage-chart [data-project] { transition: none; } }

package/src/mcp-app.js

@@ -1,3 +1,4 @@
+import { aggregateUsage } from "./usage-analytics.js";
 import { mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join } from "node:path";
@@ -78,6 +79,7 @@ export function registerTaskChefApp(server, {
   let ipcErrorReported = false;
   const turnUsageCache = new Map();
   const usagePending = new Map();
+  const analyticsJobs = new Map();
   async function boardSnapshot(settings, force = false, scope = { date: "all", taskIds: [] }) {
     const databaseSnapshot = await scanner.refresh({ force });
     await liveState.refresh(databaseSnapshot.healthy === false ? [] : databaseSnapshot.tasks);
@@ -210,6 +212,41 @@ export function registerTaskChefApp(server, {
     }
     return { structuredContent: { snapshot, settings: publicSettings(settings), settingsUrl, notifications, github: githubAuth, version: TASKCHEF_VERSION }, content: [] };
   });
+  server.registerTool("taskchef_app_usage", {
+    title: "Read usage history", description: "Aggregate timestamped local token usage and API-equivalent cost by day and project.",
+    inputSchema: { range: z.enum(["7d", "30d", "90d", "mtd", "last-month"]), timeZone: z.string().min(1).max(100), force: z.boolean().optional(), rescan: z.boolean().optional() }, _meta: appOnly,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  }, async ({ range, timeZone, force, rescan }) => {
+    new Intl.DateTimeFormat("en", { timeZone }).format();
+    const settings = await readSettings();
+    // History is independent of chart range and timezone. Range changes query
+    // this shared snapshot; only expiry or explicit Refresh starts another read.
+    const key = JSON.stringify([settings.showCli, settings.showExec]);
+    let job = analyticsJobs.get(key);
+    if ((force || rescan) && job?.pending) { job.refreshAgain = true; job.rescan ||= rescan; }
+    if (!job || (!job.pending && (force || rescan || (!job.error && Date.now() - job.finishedAt >= 60_000)))) {
+      job = { families: job?.families ?? null, error: null, finishedAt: job?.finishedAt ?? 0,
+        pending: true, refreshAgain: false, rescan: !!rescan, progress: { completed: 0, total: 0 } };
+      analyticsJobs.set(key, job);
+      const current = job;
+      Promise.resolve().then(async () => {
+        do {
+          current.refreshAgain = false;
+          const rebuild = current.rescan;
+          current.rescan = false;
+          const families = await scanner.usageHistory({ settings, rescan: rebuild, onProgress: progress => { current.progress = progress; } });
+          current.families = families;
+          current.finishedAt = Date.now();
+        } while (current.refreshAgain);
+      }).catch(error => { current.error = error; }).finally(() => { current.pending = false; });
+    }
+    if (job.error) throw job.error;
+    const data = job.families ? { ...aggregateUsage(job.families, { range, timeZone }),
+      updatedAt: new Date(job.finishedAt).toISOString(),
+      ...(job.pending ? { refreshing: true, progress: job.progress } : {}) }
+      : { loading: true, progress: job.progress };
+    return { structuredContent: data, content: [] };
+  });
   server.registerTool("taskchef_app_task", {
     title: "Read Codex chat metadata", description: "Read one local chat's metadata and its latest recorded request and response.",
     inputSchema: { taskId: taskIdSchema, refreshGithub: z.boolean().optional() }, _meta: appOnly,

package/src/usage-analytics.js

@@ -0,0 +1,47 @@
+// Calendar dates are evaluated in the view's timezone, including DST changes.
+export function aggregateUsage(families, { range, timeZone, now = Date.now() }) {
+  const format = new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' });
+  const dateKey = time => {
+    const parts = Object.fromEntries(format.formatToParts(time).map(part => [part.type, part.value]));
+    return `${parts.year}-${parts.month}-${parts.day}`;
+  };
+  let end = dateKey(now);
+  const startDate = new Date(`${end}T00:00:00Z`);
+  if (range === 'last-month') {
+    startDate.setUTCDate(1);
+    end = new Date(startDate.getTime() - 86400000).toISOString().slice(0, 10);
+    startDate.setUTCMonth(startDate.getUTCMonth() - 1);
+  } else if (range === 'mtd') startDate.setUTCDate(1);
+  else startDate.setUTCDate(startDate.getUTCDate() - ({ '7d': 6, '30d': 29, '90d': 89 }[range] ?? 29));
+  const start = startDate.toISOString().slice(0, 10);
+  const days = [];
+  for (let cursor = startDate; cursor.toISOString().slice(0, 10) <= end; cursor = new Date(cursor.getTime() + 86400000)) {
+    days.push({ date: cursor.toISOString().slice(0, 10), tokens: 0, costUsd: 0, projects: {} });
+  }
+  const byDate = new Map(days.map(day => [day.date, day]));
+  const projects = new Map();
+  let incomplete = false, samples = 0;
+  const totals = { tokens: 0, inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, costUsd: 0 };
+  for (const { project, usage } of families) {
+    // Coverage can be incomplete even when no timestamped records survive.
+    incomplete ||= usage.analyticsPartial || usage.partial || false;
+    const key = project.id === 'projectless' ? 'unassigned' : project.id || project.path || 'unassigned';
+    for (const sample of usage.timeline) {
+      if (sample.time > now) continue;
+      const day = byDate.get(dateKey(sample.time));
+      if (!day) continue;
+      let item = projects.get(key);
+      if (!item) { item = { id: key, name: key === 'unassigned' ? 'Unassigned' : project.name, tokens: 0, costUsd: 0 }; projects.set(key, item); }
+      const tokens = sample.tokens.total_tokens;
+      totals.tokens += tokens; totals.inputTokens += sample.tokens.input_tokens;
+      totals.cachedInputTokens += sample.tokens.cached_input_tokens; totals.outputTokens += sample.tokens.output_tokens;
+      totals.costUsd += sample.costUsd; samples += sample.samples;
+      day.tokens += tokens; day.costUsd += sample.costUsd;
+      day.projects[key] = (day.projects[key] ?? 0) + sample.costUsd;
+      item.tokens += tokens; item.costUsd += sample.costUsd;
+      incomplete ||= sample.partial || sample.costPartial;
+    }
+  }
+  return { start, end, timeZone, days, totals, samples, incomplete,
+    projects: [...projects.values()].sort((a, b) => b.costUsd - a.costUsd || a.name.localeCompare(b.name)) };
+}