@platys/relay 0.8.0-alpha.15 → 0.8.0-alpha.16

package/README.md

@@ -29,6 +29,11 @@ npm install --global @platys/relay
 relay setup
 ```
 
+Version **0.8.0-alpha.16** adds local token usage with `relay usage`, a separate
+browser window with `relay usage --web`, and a draggable Windows speech bubble
+with `relay usage --overlay`. Usage reads retained local provider counters and
+does not interrupt your agent or upload history.
+
 Version **0.8.0-alpha.15** adds saved peer-session selection, one-line task recaps,
 explicit conversation handover, older-session filtering, and optional shared-work
 coordination. Ordinary questions and replies remain the default. Existing clients
@@ -66,6 +71,35 @@ their agent sessions open. No shared repository or workspace selection is needed
 
 You can also ask questions from the **shared room** link shown after setup.
 
+## Token usage without interrupting your agent
+
+On Windows, run `relay usage --overlay` for a small, always-on-top speech bubble.
+Drag its heading above your Codex pet, click **Open full usage** for details, or
+use **×** to hide it. It refreshes automatically once a minute after each completed
+read. Use `--session NATIVE_ID` to keep it on one conversation; otherwise it follows
+the most recently active session with counters. Today and lifetime combine the
+selected providers' retained local history. The bubble stays where you place it;
+it does not attach to or move with the pet. Opening it and refreshing counters
+do not activate the window or send prompts to the agent. Windows PowerShell's
+built-in WPF support is required; macOS/Linux can use the browser window below.
+
+Run `relay usage --web` in another terminal to open a separate local usage window.
+The command returns immediately; your coding conversation keeps working. Pick a
+conversation to see its tokens, or check today and lifetime totals for Codex and
+Claude Code. Click **Refresh usage** for updated counters. The window is served
+locally for 30 minutes; run the command again to reopen it.
+
+Use `relay usage` for a terminal summary, `relay usage --session NATIVE_ID` for a
+specific conversation, or `relay usage --json` for all counters. Without a native
+session ID from the environment, Relay selects the most recently active session
+with recorded usage and labels it explicitly. No Relay connection is required.
+
+Usage comes from provider counters in retained local history, including work
+outside Relay. Nothing is uploaded. Lifetime covers this device's available logs;
+deleted history, other devices and inherited fork counters can affect totals.
+These totals do not represent subscription allowances or billed costs. Relay does
+not install a native Codex slash-command overlay.
+
 ## How delivery works
 
 | Recipient | What happens |

package/next/EASY_SETUP.md

@@ -3,6 +3,19 @@
 Relay connects your existing Claude Code and Codex conversations with your
 friends' agents. Each person installs it once. You do not need the same workspace.
 
+## Check token usage while your agent works
+
+With Relay 0.8.0-alpha.16 or newer, run `relay usage --overlay` on Windows for a
+draggable speech bubble. Place it above your pet; it refreshes automatically.
+Click **Open full usage** for details or **×** to hide it. The bubble does not
+move with the pet. On any supported platform, `relay usage --web` opens a separate
+browser window. Neither view sends a prompt to your agent.
+
+Update a global install with `npm install --global @platys/relay@latest`.
+Without a global install, run `npx --yes @platys/relay@latest usage --overlay`
+(Windows) or replace `--overlay` with `--web`. Usage reads retained local provider
+counters; lifetime covers this device's available history, not billing limits.
+
 ## Before you start
 
 - Install and sign in to Claude Code or Codex.

package/out/core/version.js

@@ -1 +1 @@
-export const VERSION = '0.8.0-alpha.15';
+export const VERSION = '0.8.0-alpha.16';

package/out/node/cli.js

@@ -25,10 +25,13 @@ import { setupNetwork } from './network-setup.js';
 import { openSetupWeb } from './setup-web.js';
 import { setupRemote, useRemoteSetup } from './remote-setup.js';
 import { VERSION } from '../core/version.js';
+import { readUsage, formatUsage } from './usage.js';
+import { startUsageWeb, openUsageWindow } from './usage-web.js';
+import { runUsageOverlay } from './usage-overlay.js';
 const cli = fileURLToPath(import.meta.url);
 const parsed = parseArgs({ allowPositionals: true, options: Object.fromEntries([
         'repo', 'server', 'invite', 'name', 'provider', 'repository', 'session', 'from', 'to', 'message', 'query', 'dir', 'port', 'create-key', 'args', 'id', 'backup', 'days', 'member', 'role'
-    ].map(name => [name, { type: 'string' }]).concat([['version', { type: 'boolean' }], ['approve', { type: 'boolean' }], ['json', { type: 'boolean' }], ['no-install', { type: 'boolean' }], ['no-start', { type: 'boolean' }], ['help', { type: 'boolean' }], ['relay-hook-v1', { type: 'boolean' }], ['global', { type: 'boolean' }], ['all-workspaces', { type: 'boolean' }], ['relay-network-hook-v1', { type: 'boolean' }], ['web', { type: 'boolean' }], ['no-open', { type: 'boolean' }], ['terminal', { type: 'boolean' }], ['remote', { type: 'boolean' }], ['legacy-network', { type: 'boolean' }]])) });
+    ].map(name => [name, { type: 'string' }]).concat([['version', { type: 'boolean' }], ['approve', { type: 'boolean' }], ['json', { type: 'boolean' }], ['no-install', { type: 'boolean' }], ['no-start', { type: 'boolean' }], ['help', { type: 'boolean' }], ['relay-hook-v1', { type: 'boolean' }], ['global', { type: 'boolean' }], ['all-workspaces', { type: 'boolean' }], ['relay-network-hook-v1', { type: 'boolean' }], ['web', { type: 'boolean' }], ['overlay', { type: 'boolean' }], ['no-open', { type: 'boolean' }], ['terminal', { type: 'boolean' }], ['remote', { type: 'boolean' }], ['legacy-network', { type: 'boolean' }]])) });
 const values = parsed.values, positionals = parsed.positionals;
 const option = (name) => typeof values[name] === 'string' ? values[name] : undefined;
 const help = `Relay Next — shared context for your existing coding sessions
@@ -57,6 +60,10 @@ const help = `Relay Next — shared context for your existing coding sessions
   doctor                  Check connector, MCP startup, session registration and legacy conflicts
   project                 Read accepted revision, tasks and current decisions
   metrics                 Read payload sizes and operation counts
+  usage                   Show local session, today and lifetime model tokens
+  usage --web             Open a separate usage window; keep your agent working
+  usage --overlay         Show a draggable speech bubble above your pet (Windows)
+  usage --session ID      Inspect a native conversation; --provider codex|claude --json
   budget                  Read cached shared monthly budget and pause alerts (local only)
   budget-refresh          Explicitly check whether the owner approved resuming this service
   task --args JSON        Reserve/renew/handoff/release scopes
@@ -209,6 +216,34 @@ async function main() {
         console.log(help);
         return;
     }
+    if (cmd === 'usage') {
+        const options = { provider: option('provider'), session: option('session') ?? process.env.CODEX_THREAD_ID ?? process.env.CLAUDE_CODE_SESSION_ID };
+        if (values.overlay) {
+            if (values.web)
+                throw Error('Choose --overlay or --web');
+            if (process.platform !== 'win32')
+                throw Error('The usage overlay currently requires Windows. Use relay usage --web.');
+            if (values['no-start'] && process.send) {
+                await runUsageOverlay(options, url => process.send?.(url));
+                return;
+            }
+            await openUsageWindow(cli, { ...options, overlay: true });
+            return;
+        }
+        if (values.web) {
+            if (values['no-start'] && process.send) {
+                const web = await startUsageWeb(options);
+                process.send(web.url);
+                setTimeout(() => void web.close(), 30 * 60_000).unref();
+                return;
+            }
+            await openUsageWindow(cli, { ...options, noOpen: !!values['no-open'] });
+            return;
+        }
+        const report = await readUsage(options);
+        console.log(values.json ? JSON.stringify(report, null, 2) : formatUsage(report));
+        return;
+    }
     if (cmd === 'budget') {
         console.log(JSON.stringify(clientBudget.status(), null, 2));
         return;

package/out/node/usage-overlay.js

@@ -0,0 +1,130 @@
+import { spawn } from 'node:child_process';
+import { startUsageWeb } from './usage-web.js';
+// WPF ships with Windows PowerShell. Keep UI work in its STA process and usage
+// collection in Node; an asynchronous HTTP request never blocks dragging or hiding.
+export function usageOverlayScript(url) {
+    const encoded = Buffer.from(url, 'utf8').toString('base64');
+    return String.raw `
+$ErrorActionPreference = 'Stop'
+Add-Type -AssemblyName PresentationFramework, PresentationCore, WindowsBase, System.Net.Http
+$usageUrl = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encoded}'))
+$address = [Uri]$usageUrl
+$handler = New-Object System.Net.Http.HttpClientHandler
+$handler.UseProxy = $false
+$client = New-Object System.Net.Http.HttpClient($handler)
+$client.Timeout = [TimeSpan]::FromMinutes(2)
+$client.DefaultRequestHeaders.Authorization = New-Object System.Net.Http.Headers.AuthenticationHeaderValue('Bearer', $address.Fragment.Substring(1))
+$endpoint = $address.GetLeftPart([UriPartial]::Authority) + '/api/usage'
+[xml]$xaml = @'
+<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+ Title="Relay token usage" Width="340" SizeToContent="Height" WindowStyle="None" ResizeMode="NoResize" AllowsTransparency="True" Background="Transparent" Topmost="True" ShowActivated="False" FontFamily="Segoe UI" UseLayoutRounding="True">
+ <Grid Margin="10">
+  <Grid.RowDefinitions><RowDefinition Height="Auto"/><RowDefinition Height="18"/></Grid.RowDefinitions>
+  <Border Background="#FFF9ED" BorderBrush="#D9CDB5" BorderThickness="1" CornerRadius="18" Padding="20,14,20,16">
+   <Border.Effect><DropShadowEffect BlurRadius="12" ShadowDepth="2" Opacity="0.22"/></Border.Effect>
+   <StackPanel>
+    <DockPanel LastChildFill="True" Margin="0,0,0,10">
+     <Button x:Name="Hide" DockPanel.Dock="Right" Content="&#x00D7;" Width="26" Height="26" FontSize="19" Background="Transparent" BorderThickness="0" Foreground="#615747" AutomationProperties.Name="Hide Relay usage" ToolTip="Hide. Reopen with relay usage --overlay."/>
+     <TextBlock x:Name="DragHandle" Text="RELAY USAGE" Foreground="#615747" FontSize="12" FontWeight="SemiBold" Padding="0,5,0,5" Cursor="SizeAll" ToolTip="Drag this bubble above your pet"/>
+    </DockPanel>
+    <TextBlock x:Name="SessionLabel" Text="Reading local counters..." FontSize="12" Foreground="#615747" TextWrapping="Wrap"/>
+    <TextBlock x:Name="SessionTokens" Text="..." FontSize="32" FontWeight="SemiBold" Foreground="#252A2D" Margin="0,2,0,10"/>
+    <Grid Margin="0,0,0,10"><Grid.ColumnDefinitions><ColumnDefinition/><ColumnDefinition/></Grid.ColumnDefinitions>
+     <StackPanel><TextBlock Text="TODAY" FontSize="11" Foreground="#615747"/><TextBlock x:Name="Today" Text="..." FontSize="20" Foreground="#252A2D"/></StackPanel>
+     <StackPanel Grid.Column="1"><TextBlock Text="LIFETIME" FontSize="11" Foreground="#615747"/><TextBlock x:Name="Lifetime" Text="..." FontSize="20" Foreground="#252A2D"/></StackPanel>
+    </Grid>
+    <Button x:Name="Details" Content="Open full usage  &#x2197;" HorizontalAlignment="Left" Padding="0,5" Background="Transparent" BorderThickness="0" Foreground="#225D70" FontWeight="SemiBold" AutomationProperties.Name="Open full Relay token usage in your browser"/>
+    <TextBlock x:Name="Status" Text="Local history only. Your agent keeps working." TextWrapping="Wrap" FontSize="11" Foreground="#615747" Margin="0,6,0,0"/>
+   </StackPanel>
+  </Border>
+  <Path Grid.Row="1" HorizontalAlignment="Right" Margin="0,-1,40,0" Data="M 0,0 L 22,17 L 24,0" Fill="#FFF9ED" Stroke="#D9CDB5" StrokeThickness="1"/>
+ </Grid>
+</Window>
+'@
+$reader = New-Object System.Xml.XmlNodeReader($xaml)
+$window = [Windows.Markup.XamlReader]::Load($reader)
+$sessionLabel = $window.FindName('SessionLabel')
+$sessionTokens = $window.FindName('SessionTokens')
+$today = $window.FindName('Today')
+$lifetime = $window.FindName('Lifetime')
+$status = $window.FindName('Status')
+$window.Left = [Math]::Max(0, [Windows.SystemParameters]::WorkArea.Right - $window.Width - 30)
+$window.Top = [Math]::Max(0, [Windows.SystemParameters]::WorkArea.Bottom - 420)
+$window.FindName('DragHandle').Add_MouseLeftButtonDown({ if ($_.ButtonState -eq 'Pressed') { $window.DragMove() } })
+$window.FindName('Hide').Add_Click({ $window.Close() })
+$window.FindName('Details').Add_Click({
+ try { [Diagnostics.Process]::Start($usageUrl) | Out-Null } catch { $status.Text = 'Could not open browser. Run relay usage --web.' }
+})
+function ShortTokens([double]$value) {
+ if ($value -ge 1e9) { return ($value / 1e9).ToString('0.##') + 'B' }
+ if ($value -ge 1e6) { return ($value / 1e6).ToString('0.##') + 'M' }
+ if ($value -ge 1e3) { return ($value / 1e3).ToString('0.#') + 'K' }
+ return $value.ToString('N0')
+}
+$script:request = $null
+$script:nextRefresh = [DateTime]::MinValue
+$timer = New-Object Windows.Threading.DispatcherTimer
+$timer.Interval = [TimeSpan]::FromMilliseconds(250)
+$timer.Add_Tick({
+ try { [Diagnostics.Process]::GetProcessById(${process.pid}) | Out-Null } catch { $window.Close(); return }
+ if ($null -eq $script:request) {
+  if ([DateTime]::UtcNow -lt $script:nextRefresh) { return }
+  $status.Text = 'Refreshing local counters...'
+  $script:request = $client.GetStringAsync($endpoint)
+  return
+ }
+ if (-not $script:request.IsCompleted) { return }
+ try {
+  $report = $script:request.GetAwaiter().GetResult() | ConvertFrom-Json
+  if ($null -ne $report.session) {
+   $label = if ($report.selection -eq 'requested session') { 'This session' } else { 'Most recently active session' }
+   $sessionLabel.Text = $label + ' / ' + $report.session.provider
+   $sessionLabel.ToolTip = $report.session.id
+   $sessionTokens.Text = (ShortTokens $report.session.tokens.total) + ' tokens'
+   $sessionTokens.ToolTip = $report.session.tokens.total.ToString('N0') + ' recorded tokens'
+  } else { $sessionLabel.Text = 'No session counters available'; $sessionTokens.Text = '--' }
+  [double]$dayTotal = 0; [double]$allTotal = 0; [int]$sessionCount = 0
+  foreach ($provider in $report.providers.PSObject.Properties.Value) {
+   $dayTotal += $provider.today.total; $allTotal += $provider.lifetime.total; $sessionCount += $provider.sessions
+  }
+  if ($sessionCount -gt 0) {
+   $today.Text = ShortTokens $dayTotal; $lifetime.Text = ShortTokens $allTotal
+   $today.ToolTip = $dayTotal.ToString('N0') + ' tokens / local day'
+   $lifetime.ToolTip = $allTotal.ToString('N0') + ' tokens / retained local history'
+  } else { $today.Text = '--'; $lifetime.Text = '--' }
+  $status.Text = 'Local history / updated ' + (Get-Date).ToString('HH:mm:ss')
+  if ($report.coverage.unreadable -gt 0 -or $report.coverage.malformedLines -gt 0 -or $report.coverage.sessionsWithoutCounters -gt 0) { $status.Text += ' / gaps in history' }
+  $status.ToolTip = $report.limitations
+ } catch { $status.Text = 'Refresh failed. Retrying in one minute.' }
+ $script:request = $null
+ $script:nextRefresh = [DateTime]::UtcNow.AddMinutes(1)
+})
+$window.Add_ContentRendered({ [Console]::WriteLine('RELAY_OVERLAY_READY'); [Console]::Out.Flush() })
+$window.Add_Closed({ $timer.Stop(); $client.CancelPendingRequests(); $client.Dispose(); $handler.Dispose() })
+$timer.Start()
+$window.ShowDialog() | Out-Null
+`;
+}
+export async function runUsageOverlay(options, ready) {
+    if (process.platform !== 'win32')
+        throw Error('The usage overlay currently requires Windows. Use relay usage --web on this platform.');
+    const web = await startUsageWeb(options);
+    const script = Buffer.from(usageOverlayScript(web.url), 'utf16le').toString('base64');
+    const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-STA', '-WindowStyle', 'Hidden', '-EncodedCommand', script], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let shown = false, output = '';
+    try {
+        await new Promise((done, reject) => {
+            child.stdout.on('data', chunk => { output += chunk.toString(); if (!shown && output.includes('RELAY_OVERLAY_READY')) {
+                shown = true;
+                ready(web.url);
+            } });
+            child.stderr.on('data', () => { }); // Do not expose private local URLs or PowerShell source on errors.
+            child.once('error', reject);
+            child.once('exit', code => shown && code === 0 ? done() : reject(Error('Windows could not display the Relay usage overlay.')));
+        });
+    }
+    finally {
+        child.kill();
+        await web.close();
+    }
+}

package/out/node/usage-web.js

@@ -0,0 +1,79 @@
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { fork, spawn } from 'node:child_process';
+import { readUsage } from './usage.js';
+export function usagePage(nonce) {
+    return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Relay usage</title>
+<style nonce="${nonce}">body{font:16px system-ui;background:#101820;color:#edf3f5;max-width:850px;margin:40px auto;padding:24px}h1{font-size:30px}button,select{font:inherit;padding:10px;margin:8px 8px 8px 0;max-width:100%}pre{white-space:pre-wrap;line-height:1.7}section{background:#1c2933;padding:20px;border-radius:12px;margin:16px 0}.muted{color:#b7c6ce}label{display:block}a{color:#a9d9ff}</style>
+<h1>Relay usage</h1><p class="muted">Check usage while your agent keeps working. All data stays on this device.</p><button id="refresh">Refresh usage</button><span id="updated" role="status"></span>
+<section><label for="sessions">Conversation</label><select id="sessions"></select><pre id="session"></pre></section><section><h2>Today &amp; lifetime</h2><pre id="totals"></pre></section><p id="coverage" class="muted"></p><p id="limits" class="muted"></p><p id="error" role="alert"></p>
+<script nonce="${nonce}">
+const token=location.hash.slice(1);history.replaceState(null,'',location.pathname);let data;
+const el=id=>document.getElementById(id),n=x=>x.toLocaleString(),describe=t=>n(t.total)+' total · '+n(t.input)+' input · '+n(t.output)+' output\\n'+n(t.cachedInput)+' cached input · '+n(t.cacheWrite)+' cache writes (included in input)';
+function selected(){const s=data.sessions.find(s=>s.provider+':'+s.id===el('sessions').value);el('session').textContent=s?describe(s.tokens):'No recorded token counters available.';}
+async function refresh(){el('refresh').disabled=true;el('error').textContent='';try{const r=await fetch('/api/usage',{headers:{Authorization:'Bearer '+token}});if(!r.ok)throw Error('Usage unavailable. Reopen with relay usage --web.');data=await r.json();const previous=el('sessions').value;el('sessions').replaceChildren();for(const s of data.sessions){const o=document.createElement('option');o.value=s.provider+':'+s.id;o.textContent=s.provider+' · '+s.id;el('sessions').append(o);}if([...el('sessions').options].some(o=>o.value===previous))el('sessions').value=previous;else if(data.session)el('sessions').value=data.session.provider+':'+data.session.id;selected();el('totals').textContent=Object.entries(data.providers).filter(([k,v])=>v.sessions).map(([k,v])=>k+' · '+v.sessions+' sessions\\nToday: '+n(v.today.total)+' tokens (local day)\\nLifetime: '+describe(v.lifetime)).join('\\n\\n')||'No usage history found.';el('updated').textContent='Updated '+new Date(data.asOf).toLocaleTimeString();el('coverage').textContent=data.scope+' '+data.coverage.files+' files; '+data.coverage.unreadable+' unreadable; '+data.coverage.malformedLines+' malformed/incomplete lines; '+data.coverage.sessionsWithoutCounters+' sessions without counters.';el('limits').textContent=data.limitations;}catch(e){el('error').textContent=e.message;}finally{el('refresh').disabled=false;}}
+el('sessions').onchange=selected;el('refresh').onclick=refresh;refresh();
+</script></html>`;
+}
+export async function startUsageWeb(options = {}) {
+    const token = randomBytes(32).toString('base64url');
+    let origin = '', pending;
+    const server = createServer(async (req, res) => {
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Referrer-Policy', 'no-referrer');
+        const send = (status, value) => { res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(value)); };
+        if (req.headers.host !== origin.slice(7) || req.headers.origin && req.headers.origin !== origin) {
+            send(403, { error: 'Forbidden' });
+            return;
+        }
+        if (req.method === 'GET' && req.url === '/') {
+            const nonce = randomBytes(18).toString('base64url');
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'` });
+            res.end(usagePage(nonce));
+            return;
+        }
+        if (req.headers.authorization !== 'Bearer ' + token) {
+            send(403, { error: 'Forbidden' });
+            return;
+        }
+        if (req.method !== 'GET' || req.url !== '/api/usage') {
+            send(404, { error: 'Not found' });
+            return;
+        }
+        try {
+            pending ??= readUsage(options);
+            send(200, await pending);
+        }
+        catch {
+            send(500, { error: 'Could not read local usage history' });
+        }
+        finally {
+            pending = undefined;
+        }
+    });
+    await new Promise((done, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', () => { server.off('error', reject); done(); }); });
+    origin = 'http://127.0.0.1:' + server.address().port;
+    return { url: origin + '/#' + token, close: () => new Promise((done, reject) => { server.close(error => error ? reject(error) : done()); server.closeIdleConnections(); }) };
+}
+export async function openUsageWindow(cli, options) {
+    // A separate process owns the window so the invoking agent/terminal can continue immediately.
+    const args = ['usage', options.overlay ? '--overlay' : '--web', '--no-start', ...(options.provider ? ['--provider', options.provider] : []), ...(options.session ? ['--session', options.session] : [])];
+    const child = fork(cli, args, { detached: true, windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
+    const url = await new Promise((done, reject) => {
+        const timer = setTimeout(() => { child.kill(); reject(Error('Usage window did not start')); }, 30000);
+        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('exit', () => { clearTimeout(timer); reject(Error('Usage window could not start')); });
+        child.once('message', message => { clearTimeout(timer); done(String(message)); });
+    });
+    child.disconnect();
+    child.unref();
+    console.log('Relay usage window: ' + url);
+    if (!options.noOpen && !options.overlay) {
+        const executable = process.platform === 'win32' ? 'rundll32.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+        const browser = spawn(executable, process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url], { windowsHide: true, stdio: 'ignore' });
+        browser.on('error', () => console.error('Open the usage link above in your browser.'));
+        browser.unref();
+    }
+    return { url, pid: child.pid };
+}

package/out/node/usage.js

@@ -0,0 +1,158 @@
+import { createReadStream } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const empty = () => ({ input: 0, output: 0, cachedInput: 0, cacheWrite: 0, total: 0 });
+const count = (x) => Number.isSafeInteger(x) && Number(x) >= 0;
+const add = (a, b) => { for (const key of Object.keys(a))
+    a[key] += b[key]; return a; };
+function counters(raw, provider) {
+    if (!raw || !count(raw.input_tokens) || !count(raw.output_tokens))
+        return;
+    const cached = provider === 'codex' ? raw.cached_input_tokens : raw.cache_read_input_tokens;
+    const written = provider === 'codex' ? raw.cache_write_input_tokens : raw.cache_creation_input_tokens;
+    if (cached !== undefined && !count(cached) || written !== undefined && !count(written))
+        return;
+    // Codex includes cached tokens in input; Claude reports three disjoint input buckets.
+    const input = raw.input_tokens + (provider === 'claude' ? (cached ?? 0) + (written ?? 0) : 0);
+    return { input, output: raw.output_tokens, cachedInput: cached ?? 0, cacheWrite: written ?? 0, total: input + raw.output_tokens };
+}
+export async function readUsage(options = {}) {
+    if (options.provider && !['codex', 'claude'].includes(options.provider))
+        throw Error('Usage provider must be codex or claude');
+    const sessions = new Map(), coverage = { files: 0, unreadable: 0, malformedLines: 0, sessionsWithoutCounters: 0 };
+    const scan = async (dir, provider) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                coverage.unreadable++;
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await scan(path, provider);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+                continue;
+            coverage.files++;
+            let nativeId = provider === 'claude' ? entry.name.slice(0, -6) : undefined;
+            const stream = createReadStream(path, { encoding: 'utf8' }), lines = createInterface({ input: stream, crlfDelay: Infinity });
+            try {
+                for await (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    // Skip conversation bodies before JSON parsing; only counter records are relevant.
+                    if (provider === 'codex' && !line.includes('session_meta') && !line.includes('token_count'))
+                        continue;
+                    if (provider === 'claude' && !line.includes('"usage"'))
+                        continue;
+                    let record;
+                    try {
+                        record = JSON.parse(line);
+                    }
+                    catch {
+                        coverage.malformedLines++;
+                        continue;
+                    }
+                    if (provider === 'codex' && record.type === 'session_meta' && typeof record.payload?.id === 'string')
+                        nativeId = record.payload.id;
+                    if (provider === 'claude' && typeof record.sessionId === 'string')
+                        nativeId = record.sessionId;
+                    if (!nativeId)
+                        continue;
+                    const key = provider + ':' + nativeId;
+                    let session = sessions.get(key);
+                    if (!session) {
+                        session = { id: nativeId, provider, samples: new Map(), seenAt: '' };
+                        sessions.set(key, session);
+                    }
+                    const at = typeof record.timestamp === 'string' && Number.isFinite(Date.parse(record.timestamp)) ? new Date(record.timestamp).toISOString() : '';
+                    const raw = provider === 'codex' ? (record.type === 'event_msg' && record.payload?.type === 'token_count' ? record.payload.info?.total_token_usage : undefined) : (record.type === 'assistant' ? record.message?.usage : undefined);
+                    const tokens = counters(raw, provider);
+                    if (!tokens || !at)
+                        continue;
+                    const sampleKey = provider === 'codex' ? at : record.message?.id;
+                    // Claude may repeat an assistant message while streaming; keep its final counters.
+                    if (typeof sampleKey !== 'string')
+                        continue;
+                    const previous = session.samples.get(sampleKey);
+                    if (!previous || tokens.total >= previous.tokens.total)
+                        session.samples.set(sampleKey, { at, tokens });
+                    if (at > session.seenAt)
+                        session.seenAt = at;
+                }
+            }
+            catch {
+                coverage.unreadable++;
+            }
+            finally {
+                lines.close();
+                stream.destroy();
+            }
+        }
+    };
+    if (!options.provider || options.provider === 'codex') {
+        const home = options.codexHome ?? process.env.CODEX_HOME ?? join(homedir(), '.codex');
+        await scan(join(home, 'sessions'), 'codex');
+        await scan(join(home, 'archived_sessions'), 'codex');
+    }
+    if (!options.provider || options.provider === 'claude')
+        await scan(join(options.claudeHome ?? process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'projects'), 'claude');
+    const now = options.now ?? new Date(), day = new Date(now);
+    day.setHours(0, 0, 0, 0);
+    const providers = { codex: { lifetime: empty(), today: empty(), sessions: 0 }, claude: { lifetime: empty(), today: empty(), sessions: 0 } };
+    const results = [];
+    for (const session of sessions.values()) {
+        if (!session.samples.size) {
+            coverage.sessionsWithoutCounters++;
+            continue;
+        }
+        const lifetime = empty(), today = empty();
+        let previous = empty();
+        for (const sample of [...session.samples.values()].sort((a, b) => a.at.localeCompare(b.at))) {
+            let delta = sample.tokens;
+            if (session.provider === 'codex') {
+                delta = empty();
+                for (const key of Object.keys(delta))
+                    delta[key] = Math.max(0, sample.tokens[key] - previous[key]);
+                // Repeated snapshots and resumed/archived copies cannot add usage twice.
+                for (const key of Object.keys(previous))
+                    previous[key] = Math.max(previous[key], sample.tokens[key]);
+            }
+            add(lifetime, delta);
+            if (Date.parse(sample.at) >= day.getTime() && Date.parse(sample.at) <= now.getTime())
+                add(today, delta);
+        }
+        add(providers[session.provider].lifetime, lifetime);
+        add(providers[session.provider].today, today);
+        providers[session.provider].sessions++;
+        results.push({ id: session.id, provider: session.provider, lastUsageAt: session.seenAt, tokens: lifetime });
+    }
+    results.sort((a, b) => b.lastUsageAt.localeCompare(a.lastUsageAt));
+    const selected = options.session ? results.find(s => s.id === options.session) : results[0];
+    if (options.session && !selected)
+        throw Error('No token counters found for that native session ID on this device');
+    return { scope: 'Local provider history on this device; includes all agent work, not just Relay messages.', asOf: now.toISOString(), todayStartsAt: day.toISOString(), selection: options.session ? 'requested session' : 'most recently active session with counters', session: selected ?? null, sessions: results, providers, coverage,
+        limitations: 'Lifetime covers retained local logs only. Deleted history, other devices, and forks with inherited counters can affect totals. These are recorded token counts, not subscription limits or billed costs.' };
+}
+export function formatUsage(report) {
+    const number = (value) => value.toLocaleString('en-US');
+    const lines = ['Relay token usage · this device', report.scope, ''];
+    if (report.session)
+        lines.push(`Session (${report.selection}): ${report.session.provider} ${report.session.id}`, `  ${number(report.session.tokens.total)} total · ${number(report.session.tokens.input)} input · ${number(report.session.tokens.output)} output`);
+    else
+        lines.push('Session: unavailable — no recorded token counters found.');
+    for (const [provider, value] of Object.entries(report.providers))
+        if (value.sessions)
+            lines.push('', `${provider} · ${value.sessions} sessions`, `  Today:    ${number(value.today.total)} tokens (local day)`, `  Lifetime: ${number(value.lifetime.total)} tokens · ${number(value.lifetime.input)} input · ${number(value.lifetime.output)} output`, `  Cached input: ${number(value.lifetime.cachedInput)} · cache writes: ${number(value.lifetime.cacheWrite)} (included in input)`);
+    lines.push('', `Coverage: ${report.coverage.files} files · ${report.coverage.unreadable} unreadable · ${report.coverage.malformedLines} malformed/incomplete lines · ${report.coverage.sessionsWithoutCounters} sessions without counters`, report.limitations, '', 'Use relay usage --session NATIVE_ID for a specific conversation; --json for full counters.');
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platys/relay",
-  "version": "0.8.0-alpha.15",
+  "version": "0.8.0-alpha.16",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
@@ -39,6 +39,7 @@
     "test:hosted": "npm run build && node out/tests/hosted-smoke.js",
     "test:native": "npm run build && node out/tests/native-smoke.js",
     "test:claude-native": "npm run build && node next/tests/claude-session-native-smoke.mjs",
+    "test:usage-overlay": "npm run build && node next/tests/usage-overlay-smoke.mjs",
     "test:coordination-native": "npm run build && node next/tests/coordination-native-smoke.mjs",
     "prepack": "npm run build",
     "worker:dev": "wrangler dev --config next/worker/wrangler.jsonc",