From 9d3d7f409d45d9b887be3d8f51304be8f43dbefc Mon Sep 17 00:00:00 2001 From: devops Date: Fri, 23 Oct 2026 13:34:20 +0000 Subject: [PATCH] fix(admin): distinguish snapshot inventory from live runtime telemetry --- .../src/components/RuntimeReadPanel.test.tsx | 13 +++++++++ .../src/components/RuntimeReadPanel.tsx | 13 +++++---- .../admin-panel/src/services/runtime.test.ts | 21 ++++++++++++++ frontend/admin-panel/src/services/runtime.ts | 28 ++++++++++++------- 4 files changed, 59 insertions(+), 16 deletions(-) create mode 100644 frontend/admin-panel/src/services/runtime.test.ts diff --git a/frontend/admin-panel/src/components/RuntimeReadPanel.test.tsx b/frontend/admin-panel/src/components/RuntimeReadPanel.test.tsx index 78cb379e..48f22ecc 100644 --- a/frontend/admin-panel/src/components/RuntimeReadPanel.test.tsx +++ b/frontend/admin-panel/src/components/RuntimeReadPanel.test.tsx @@ -2,6 +2,19 @@ import {render,screen,fireEvent,waitFor} from '@testing-library/react'; import {beforeEach,it,expect,vi} from 'vitest'; import api from '../services/api'; import RuntimeReadPanel from './RuntimeReadPanel'; +const provenance={source:'snapshot',capturedAt:'2020-01-01T00:00:00Z',ageSeconds:5000,freshness:'stale',liveProcess:'unknown'}; +it('labels snapshot inventory without presenting stopped gateway, zero agents or active sessions as live',async()=>{ + vi.mocked(api.get).mockImplementation(async url=>({data:url.endsWith('/health')?{ok:true,version:'v1',commit:'abc',auth_required:true,provenance}:url.endsWith('/profiles')?[{name:'dev',is_default:false,gateway_running:false,liveGatewayState:'unknown',provenance}]:url.endsWith('/status')?{version:'v1',gateway_running:false,overall:'unknown',active_agents:0,gateway_state:null,liveGatewayState:'unknown',liveActiveAgents:null,provenance}:url.endsWith('/sessions')?{total:1,sessions:[{id:'session-1',profile:'dev',source:'cli',is_active:true}],provenance}:{period_days:30,totals:{total_input:1,total_output:2,total_sessions:1,total_estimated_cost:0},provenance}})); + render(); + expect(await screen.findByText('Inventory service: responsive (not live Hermes health)')).toBeInTheDocument(); + screen.getAllByText(/Captured at: 2020-01-01T00:00:00Z/).forEach(row=>expect(row).toHaveTextContent('stale')); + fireEvent.change(screen.getByLabelText('Authorized runtime profile'),{target:{value:'dev'}}); + expect(await screen.findByText(/Active agents: unknown/)).toBeInTheDocument(); + expect(await screen.findByText(/historical snapshot flag: active; live activity unknown/)).toBeInTheDocument(); + expect(screen.queryByText(/Gateway.*stopped/)).not.toBeInTheDocument(); + expect(screen.queryByText(/Active agents: 0/)).not.toBeInTheDocument(); + expect(screen.queryByText(/runtime health: healthy/)).not.toBeInTheDocument(); +}); vi.mock('../services/api',()=>({default:{get:vi.fn()}})); beforeEach(()=>{vi.resetAllMocks();vi.mocked(api.get).mockImplementation(async url=>{ if(url.endsWith('/health'))return {data:{ok:true,version:'v1',commit:'abc',auth_required:true}}; diff --git a/frontend/admin-panel/src/components/RuntimeReadPanel.tsx b/frontend/admin-panel/src/components/RuntimeReadPanel.tsx index 636831dc..fe0ff503 100644 --- a/frontend/admin-panel/src/components/RuntimeReadPanel.tsx +++ b/frontend/admin-panel/src/components/RuntimeReadPanel.tsx @@ -1,7 +1,8 @@ import {useEffect,useState} from 'react'; import Button from './ui/Button'; import {runtime} from '../services/runtime'; -import type {RuntimeHealth,RuntimeProfile,RuntimeStatus,RuntimeSessions,RuntimeUsage} from '../services/runtime'; +import type {RuntimeProvenance,RuntimeHealth,RuntimeProfile,RuntimeStatus,RuntimeSessions,RuntimeUsage} from '../services/runtime'; +function Snapshot({value}:{value?:RuntimeProvenance}){return value?

Snapshot inventory · Captured at: {value.capturedAt} · Age: {value.ageSeconds} seconds · {value.freshness} · Live process: {value.liveProcess}. Even fresh snapshots are not live readiness.

:null} export default function RuntimeReadPanel(){ const [revision,setRevision]=useState(0);const [profile,setProfile]=useState('');const [offset,setOffset]=useState(0); const [health,setHealth]=useState(null);const [profiles,setProfiles]=useState([]);const [errors,setErrors]=useState>({}); @@ -23,12 +24,12 @@ export default function RuntimeReadPanel(){

Hermes runtime — backend authenticated reads

No browser runtime credentials or direct Hermes connection. Refresh observations are not heartbeat timestamps.

{Object.entries(errors).filter(([,message])=>message).map(([name,message])=>

{message}

)} - {health&&

Authenticated runtime health: {health.ok?'healthy':'unhealthy'}

{health.version} · {health.commit}

Client observed at: {observed}. Source freshness unknown.

} + {health&&

Inventory service: {health.ok?'responsive':'not responsive'} (not live Hermes health)

{health.version} · {health.commit}

Client observed at: {observed}. Client receipt time only; not capture time or live heartbeat.

} {!profiles.length&&!errors.profiles&&

No authorized profiles returned.

} - {profiles.map(p=>

{p.name} · Gateway {p.gateway_running?'running':'stopped'} · {p.is_default?'default profile':'non-default profile'}

)} - {status&&

Profile status

{status.overall}

Gateway: {status.gateway_running?'running':'stopped'} · State: {status.gateway_state??'Unknown'} · Active agents: {status.active_agents}

} - {usage&&

Runtime usage — {usage.period_days} days, selected profile only

Input tokens: {usage.totals.total_input}

Output tokens: {usage.totals.total_output}

Sessions: {usage.totals.total_sessions}

Upstream estimated cost: {usage.totals.total_estimated_cost} (currency unspecified by source; not settled billing)

Do not add this to 9router totals; attribution overlaps and is not reconciled.

} - {sessions&&

Sessions — {sessions.total} returned total

{!sessions.sessions.length&&

No sessions returned.

}{sessions.sessions.map(s=>

{s.id} · {s.profile} · {s.source} · {s.is_active?'active':'inactive'}

)}
} + {profiles.map(p=>
{p.name} · Gateway {p.provenance?'unknown (snapshot; not process readiness)':p.gateway_running?'running':'stopped'} · {p.is_default?'default profile':'non-default profile'}
)} + {status&&

Profile status

{status.overall}

Gateway: {status.provenance?'unknown':status.gateway_running?'running':'stopped'} · State: {status.provenance?'unknown':status.gateway_state??'Unknown'} · Active agents: {status.provenance?'unknown':status.active_agents}

} + {usage&&

Runtime usage — {usage.period_days} days, selected profile only

Input tokens: {usage.totals.total_input}

Output tokens: {usage.totals.total_output}

Sessions: {usage.totals.total_sessions}

Upstream estimated cost: {usage.totals.total_estimated_cost} (currency unspecified by source; not settled billing)

Do not add this to 9router totals; attribution overlaps and is not reconciled.

} + {sessions&&

Sessions — {sessions.total} returned total

{!sessions.sessions.length&&

No sessions returned.

}{sessions.sessions.map(s=>

{s.id} · {s.profile} · {s.source} · {sessions.provenance?`historical snapshot flag: ${s.is_active?'active':'inactive'}; live activity unknown`:s.is_active?'active':'inactive'}

)}
} ; } diff --git a/frontend/admin-panel/src/services/runtime.test.ts b/frontend/admin-panel/src/services/runtime.test.ts new file mode 100644 index 00000000..de3ca112 --- /dev/null +++ b/frontend/admin-panel/src/services/runtime.test.ts @@ -0,0 +1,21 @@ +import {it,expect,vi} from 'vitest'; +import api from './api'; +import {runtime} from './runtime'; +vi.mock('./api',()=>({default:{get:vi.fn()}})); +const provenance={source:'snapshot',capturedAt:'2020-01-01T00:00:00Z',ageSeconds:100,freshness:'stale',liveProcess:'unknown'}; +it.each([{source:'live'},{capturedAt:'not-a-date'},{capturedAt:'2999-01-01T00:00:00Z'},{ageSeconds:-1},{ageSeconds:0.5},{freshness:'live'},{liveProcess:'running'}])('rejects invalid provenance %j',async invalid=>{ + vi.mocked(api.get).mockResolvedValue({data:{ok:true,version:'1',commit:'x',auth_required:true,provenance:{...provenance,...invalid}}}); + await expect(runtime.health()).rejects.toThrow('Invalid snapshot provenance'); +}); +it('retains fresh snapshots as inventory with unknown process state',async()=>{ + vi.mocked(api.get).mockResolvedValue({data:{ok:true,version:'1',commit:'x',auth_required:true,provenance:{...provenance,freshness:'fresh'}}}); + expect(await runtime.health()).toMatchObject({provenance:{freshness:'fresh',liveProcess:'unknown'}}); +}); +it('retains validated snapshot provenance and unknown live telemetry across inventory reads',async()=>{ + vi.mocked(api.get).mockImplementation(async url=>({data:url.endsWith('/health')?{ok:true,version:'1',commit:'x',auth_required:true,provenance}:url.endsWith('/profiles')?[{name:'dev',is_default:false,gateway_running:false,liveGatewayState:'unknown',provenance}]:url.endsWith('/status')?{version:'1',overall:'unknown',gateway_running:false,active_agents:0,gateway_state:null,liveGatewayState:'unknown',liveActiveAgents:null,provenance}:url.endsWith('/sessions')?{total:0,sessions:[],provenance}:{period_days:30,totals:{total_input:0,total_output:0,total_sessions:0,total_estimated_cost:0},provenance}})); + expect(await runtime.health()).toMatchObject({provenance}); + expect(await runtime.profiles()).toMatchObject([{provenance,liveGatewayState:'unknown'}]); + expect(await runtime.status('dev')).toMatchObject({provenance,liveGatewayState:'unknown',liveActiveAgents:null}); + expect(await runtime.sessions('dev')).toMatchObject({provenance}); + expect(await runtime.usage('dev')).toMatchObject({provenance}); +}); diff --git a/frontend/admin-panel/src/services/runtime.ts b/frontend/admin-panel/src/services/runtime.ts index 9fd08d42..8c32c3ff 100644 --- a/frontend/admin-panel/src/services/runtime.ts +++ b/frontend/admin-panel/src/services/runtime.ts @@ -1,20 +1,28 @@ import api from './api'; -export interface RuntimeHealth {ok:boolean;version:string;commit:string;auth_required:true} -export interface RuntimeProfile {name:string;is_default:boolean;gateway_running:boolean} -export interface RuntimeStatus {version:string;gateway_running:boolean;overall:string;active_agents:number;gateway_state:string|null} +export interface RuntimeProvenance {source:'snapshot';capturedAt:string;ageSeconds:number;freshness:'fresh'|'stale';liveProcess:'unknown'} +interface Inventory {provenance?:RuntimeProvenance} +export interface RuntimeHealth extends Inventory {ok:boolean;version:string;commit:string;auth_required:true} +export interface RuntimeProfile extends Inventory {name:string;is_default:boolean;gateway_running:boolean;liveGatewayState?:'unknown'} +export interface RuntimeStatus extends Inventory {version:string;gateway_running:boolean;overall:string;active_agents:number;gateway_state:string|null;liveGatewayState?:'unknown';liveActiveAgents?:null} export interface RuntimeSession {id:string;profile:string;source:string;is_active:boolean} -export interface RuntimeSessions {total:number;sessions:RuntimeSession[]} -export interface RuntimeUsage {period_days:number;totals:{total_input:number;total_output:number;total_sessions:number;total_estimated_cost:number}} +export interface RuntimeSessions extends Inventory {total:number;sessions:RuntimeSession[]} +export interface RuntimeUsage extends Inventory {period_days:number;totals:{total_input:number;total_output:number;total_sessions:number;total_estimated_cost:number}} function object(value:unknown):Record{if(!value||typeof value!=='object'||Array.isArray(value))throw new Error('Invalid runtime contract');return value as Record} function text(value:unknown):string{if(typeof value!=='string')throw new Error('Invalid runtime text');return value} function bool(value:unknown):boolean{if(typeof value!=='boolean')throw new Error('Invalid runtime flag');return value} function count(value:unknown):number{if(typeof value!=='number'||!Number.isFinite(value)||value<0)throw new Error('Invalid runtime count');return value} function list(value:unknown):unknown[]{if(!Array.isArray(value)||value.length>1000)throw new Error('Invalid runtime list');return value} async function read(path:string,params?:Record):Promise{const {data}=await api.get('/admin/orchestration/runtime/'+path,...(params?[{params}]:[]));const row=data&&typeof data==='object'&&!Array.isArray(data)?data:null;if(row&&'success' in row){if(row.success!==true)throw new Error('Runtime unavailable');return row.data}return data} +function provenance(r:Record):Inventory { + if(r.provenance===undefined)return {}; + const p=object(r.provenance); + if(p.source!=='snapshot'||p.liveProcess!=='unknown'||typeof p.capturedAt!=='string'||!p.capturedAt.endsWith('Z')||!Number.isFinite(Date.parse(p.capturedAt))||Date.parse(p.capturedAt)>Date.now()||typeof p.ageSeconds!=='number'||!Number.isInteger(p.ageSeconds)||p.ageSeconds<0||!['fresh','stale'].includes(String(p.freshness)))throw new Error('Invalid snapshot provenance'); + return {provenance:{source:'snapshot',capturedAt:p.capturedAt,ageSeconds:p.ageSeconds,freshness:p.freshness as 'fresh'|'stale',liveProcess:'unknown'}}; +} export const runtime={ - async health():Promise{const r=object(await read('health'));if(r.auth_required!==true)throw new Error('Authenticated runtime required');return {ok:bool(r.ok),version:text(r.version),commit:text(r.commit),auth_required:true}}, - async profiles():Promise{return list(await read('profiles')).map(value=>{const r=object(value);return {name:text(r.name),is_default:bool(r.is_default),gateway_running:bool(r.gateway_running)}})}, - async status(profile:string):Promise{const r=object(await read('status',{profile}));return {version:text(r.version),gateway_running:bool(r.gateway_running),overall:text(r.overall),active_agents:count(r.active_agents),gateway_state:r.gateway_state===null?null:text(r.gateway_state)}}, - async sessions(profile:string,offset=0):Promise{const r=object(await read('sessions',{profile,limit:20,offset}));return {total:count(r.total),sessions:list(r.sessions).map(value=>{const s=object(value);if(s.profile!==profile)throw new Error('Runtime profile mismatch');return {id:text(s.id),profile:text(s.profile),source:text(s.source),is_active:bool(s.is_active)}})}}, - async usage(profile:string):Promise{const r=object(await read('usage',{profile,days:30}));const t=object(r.totals);return {period_days:count(r.period_days),totals:{total_input:count(t.total_input),total_output:count(t.total_output),total_sessions:count(t.total_sessions),total_estimated_cost:count(t.total_estimated_cost)}}}, + async health():Promise{const r=object(await read('health'));if(r.auth_required!==true)throw new Error('Authenticated runtime required');return {...provenance(r),ok:bool(r.ok),version:text(r.version),commit:text(r.commit),auth_required:true}}, + async profiles():Promise{return list(await read('profiles')).map(value=>{const r=object(value);return {...provenance(r),...(r.provenance?{liveGatewayState:'unknown' as const}:{}),name:text(r.name),is_default:bool(r.is_default),gateway_running:bool(r.gateway_running)}})}, + async status(profile:string):Promise{const r=object(await read('status',{profile}));return {...provenance(r),...(r.provenance?{liveGatewayState:'unknown' as const,liveActiveAgents:null}:{}),version:text(r.version),gateway_running:bool(r.gateway_running),overall:text(r.overall),active_agents:count(r.active_agents),gateway_state:r.gateway_state===null?null:text(r.gateway_state)}}, + async sessions(profile:string,offset=0):Promise{const r=object(await read('sessions',{profile,limit:20,offset}));return {...provenance(r),total:count(r.total),sessions:list(r.sessions).map(value=>{const s=object(value);if(s.profile!==profile)throw new Error('Runtime profile mismatch');return {id:text(s.id),profile:text(s.profile),source:text(s.source),is_active:bool(s.is_active)}})}}, + async usage(profile:string):Promise{const r=object(await read('usage',{profile,days:30}));const t=object(r.totals);return {...provenance(r),period_days:count(r.period_days),totals:{total_input:count(t.total_input),total_output:count(t.total_output),total_sessions:count(t.total_sessions),total_estimated_cost:count(t.total_estimated_cost)}}}, };