feat(admin): add backend-authoritative orchestration command center and usage view

This commit is contained in:
devops committed 2026-10-22 18:54:24 +00:00
1 parent e5c83e87fe
commit c8a3f35b0a
16 files changed
+510 -373

No files matched your search

@@ -0,0 +1,54 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
import api from './api';
import { orchestration } from './orchestration';
import type { Task } from './orchestration';
vi.mock('./api', () => ({ default: { get: vi.fn(), post: vi.fn(), put: vi.fn() } }));
const task = {id:'t/1',version:7,state:'GATE2_PENDING',availableActions:[{id:'approve',label:'Approve',gate:2,decision:'APPROVED'}]} as Task;
describe('orchestration adapter', () => {
beforeEach(() => vi.resetAllMocks());
it('loads bare task lists through existing authenticated client and fails closed without actions', async () => {
vi.mocked(api.get).mockResolvedValue({data:[{id:'t1',title:'Bounded work',version:2,state:'READY'}]});
const tasks = await orchestration.tasks();
expect(api.get).toHaveBeenCalledWith('/admin/orchestration/tasks');
expect(tasks[0].availableActions).toEqual([]);
});
it('rejects unadvertised transitions and incomplete Gate2 binding without a request', async () => {
await expect(orchestration.command(task, {id:'invented',label:'Run',toState:'RUNNING'}, {idempotencyKey:'k',reason:'reviewed'})).rejects.toThrow(/advertised/);
await expect(orchestration.command(task, task.availableActions[0], {idempotencyKey:'k',expiresAt:'2099-01-01T00:00:00Z'})).rejects.toThrow(/binding/);
expect(api.put).not.toHaveBeenCalled(); expect(api.post).not.toHaveBeenCalled();
});
it('binds Gate2 to immutable registered run and sends version and retry-stable key', async () => {
const run={id:'r',commitSha:'abc',environment:'staging',status:'VERIFIED',artifacts:[{id:'a',sha256:'a'.repeat(64)}]};
const input={idempotencyKey:'same-key',expiresAt:'2099-01-01T00:00:00Z',runId:'r',artifactHash:'a'.repeat(64)};
vi.mocked(api.post).mockRejectedValueOnce(new Error('network')).mockResolvedValueOnce({data:{id:'decision'}});
await expect(orchestration.command({...task,runs:[run]},task.availableActions[0],input)).rejects.toThrow('network');
await orchestration.command({...task,runs:[run]},task.availableActions[0],input);
expect(api.post).toHaveBeenLastCalledWith('/admin/orchestration/tasks/t%2F1/gates/2/decide',{expectedVersion:7,idempotencyKey:'same-key',decision:'APPROVED',expiresAt:input.expiresAt,notes:undefined,runId:'r',artifactHash:'a'.repeat(64),commitSha:'abc',environment:'staging'});
});
it('refuses expired approvals and unknown artifacts', async () => {
await expect(orchestration.command(task,task.availableActions[0],{idempotencyKey:'k',expiresAt:'2000-01-01T00:00:00Z'})).rejects.toThrow(/expiry/);
const bad={...task,runs:[{id:'r',commitSha:'abc',environment:'staging',status:'DONE',artifacts:[]}]};
await expect(orchestration.command(bad,task.availableActions[0],{idempotencyKey:'k',expiresAt:'2099-01-01T00:00:00Z',runId:'r',artifactHash:'bad'})).rejects.toThrow(/binding/);
});
it('loads immutable detail and rejects malformed optional resources', async () => {
vi.mocked(api.get).mockResolvedValueOnce({data:{success:true,data:{...task,runs:[]}}}).mockResolvedValueOnce({data:{nonsense:true}});
expect((await orchestration.task('t/1')).version).toBe(7);
await expect(orchestration.resource('agents')).rejects.toThrow(/Invalid/);
});
it('requires kill reason and uses only typed message bridge', async () => {
await expect(orchestration.kill('EMERGENCY_HALT','')).rejects.toThrow(/reason/);
await expect(orchestration.chat('session',' ','key')).rejects.toThrow(/message/);
vi.mocked(api.put).mockResolvedValue({data:{active:true}});
await orchestration.kill('STOP_AGENTS','Incident review');
expect(api.put).toHaveBeenCalledWith('/admin/orchestration/kill-switch',{level:'STOP_AGENTS',reason:'Incident review'});
vi.mocked(api.post).mockResolvedValue({data:{id:'reply',role:'assistant',content:'Review complete'}});
expect(await orchestration.chat('session','Review task','key')).toEqual({id:'reply',role:'assistant',content:'Review complete'});
expect(api.post).toHaveBeenCalledWith('/admin/orchestration/chat/messages',{sessionId:'session',message:'Review task',idempotencyKey:'key'});
});
it('creates bounded work without permitting invalid caps or client-supplied state',async()=>{
await expect(orchestration.create({key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:-1,metadata:{scope:'staging',acceptanceCriteria:['report']}})).rejects.toThrow(/budget/);
vi.mocked(api.post).mockResolvedValue({data:{id:'new-task'}});
await orchestration.create({key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:0,metadata:{scope:'staging',acceptanceCriteria:['report']}});
expect(api.post).toHaveBeenCalledWith('/admin/orchestration/tasks',{key:'t',title:'Audit',department:'SEO',operationMode:'PREPARE',budgetLimitCents:0,metadata:{scope:'staging',acceptanceCriteria:['report']}});
});
});
@@ -0,0 +1,64 @@
import api from './api';
export interface ServerAction { id: string; label: string; toState?: string; gate?: 1 | 2; decision?: 'APPROVED' | 'REJECTED'; disabledReason?: string }
export interface Artifact { id: string; sha256: string; kind?: string; uri?: string }
export interface Run { id: string; commitSha: string; environment: string; status: string; artifacts: Artifact[] }
export interface Task { id: string; key: string; title: string; department: string; state: string; version: number; operationMode: string; budgetLimitCents: number; metadata?: Record<string, unknown>; availableActions: ServerAction[]; runs?: Run[]; decisions?: Record<string, unknown>[]; events?: Record<string, unknown>[]; budgetLedger?: Record<string, unknown>[] }
export interface CommandInput { idempotencyKey: string; reason?: string; expiresAt?: string; runId?: string; artifactHash?: string }
export type Resource = 'agents' | 'model-policy' | 'schedules' | 'releases' | 'overview';
export interface ResourceSnapshot { items: Array<{id:string; title?:string; status?:string; department?:string; readiness?:string; model?:string; budgetLimitCents?:number; spentCents?:number; cron?:string; timezone?:string; environment?:string; commitSha?:string; reason?:string}>; measuredAt: string }
export const killLevels = ['FREEZE_NEW_WORK','STOP_AGENTS','DISABLE_MUTATIONS','EMERGENCY_HALT'] as const;
export type KillLevel = typeof killLevels[number];
export interface ChatMessage {id:string;role:'assistant'|'user';content:string}
function unwrap<T>(data: T | {success:boolean;data:T}): T { if (data && typeof data === 'object' && 'success' in data) {if (!data.success) throw new Error('Orchestration request failed'); return data.data;} return data as T; }
export interface CreateTaskInput {key:string;title:string;department:string;operationMode:'OBSERVE'|'PREPARE'|'MUTATE_PRODUCTION';budgetLimitCents:number;metadata:{scope:string;acceptanceCriteria:string[]}}
export const orchestration = {
async create(input:CreateTaskInput):Promise<unknown> {
if(!Number.isSafeInteger(input.budgetLimitCents)||input.budgetLimitCents<0)throw new Error('Nonnegative integer budget required');
if(!input.key.trim()||!input.title.trim()||!input.department.trim()||!input.metadata.scope.trim()||!input.metadata.acceptanceCriteria.length)throw new Error('Bounded scope and acceptance criteria required');
return (await api.post('/admin/orchestration/tasks',{key:input.key,title:input.title,department:input.department,operationMode:input.operationMode,budgetLimitCents:input.budgetLimitCents,metadata:input.metadata})).data;
},
async task(id:string):Promise<Task> {
const data=unwrap<Task>((await api.get('/admin/orchestration/tasks/'+encodeURIComponent(id))).data);
if (!data?.id || !Number.isInteger(data.version)) throw new Error('Invalid task detail');
return {...data,availableActions:data.availableActions??[]};
},
async resource(name:Resource):Promise<ResourceSnapshot> {
const data=unwrap<ResourceSnapshot>((await api.get('/admin/orchestration/'+name)).data);
if (!Array.isArray(data?.items) || !data.measuredAt) throw new Error('Invalid resource snapshot');
return data;
},
async kill(level:KillLevel,reason:string):Promise<unknown> {
if (!killLevels.includes(level) || !reason.trim()) throw new Error('Kill switch level and reason required');
return (await api.put('/admin/orchestration/kill-switch',{level,reason})).data;
},
async chat(sessionId:string,message:string,idempotencyKey:string):Promise<ChatMessage> {
if (!sessionId.trim() || !message.trim() || !idempotencyKey) throw new Error('Session and message required');
const data=unwrap<ChatMessage>((await api.post('/admin/orchestration/chat/messages',{sessionId,message,idempotencyKey})).data);
if (!data?.id || data.role!=='assistant' || typeof data.content!=='string') throw new Error('Invalid typed chat reply');
return data;
},
async command(task: Task, requested: ServerAction, input: CommandInput): Promise<unknown> {
const action = task.availableActions.find(a => a.id === requested.id);
if (!action || action.disabledReason) throw new Error('Action is not advertised or is disabled');
if (!input.idempotencyKey || !Number.isInteger(task.version)) throw new Error('Version and idempotency key required');
const base = '/admin/orchestration/tasks/' + encodeURIComponent(task.id);
if (action.gate && action.decision) {
if (!input.expiresAt || !(Date.parse(input.expiresAt) > Date.now())) throw new Error('Future expiry required');
let binding = {};
if (action.gate === 2 && action.decision === 'APPROVED') {
const run = task.runs?.find(r => r.id === input.runId);
if (!run?.commitSha || !run.environment || !run.artifacts.some(a => a.sha256 === input.artifactHash)) throw new Error('Registered immutable Gate2 binding required');
binding = {runId:run.id, artifactHash:input.artifactHash, commitSha:run.commitSha, environment:run.environment};
}
return (await api.post(base + `/gates/${action.gate}/decide`, {expectedVersion:task.version,idempotencyKey:input.idempotencyKey,decision:action.decision,expiresAt:input.expiresAt,notes:input.reason,...binding})).data;
}
if (!action.toState) throw new Error('Unsupported server action');
return (await api.put(base + '/transition', {toState:action.toState,expectedVersion:task.version,idempotencyKey:input.idempotencyKey,reason:input.reason})).data;
},
async tasks(): Promise<Task[]> {
const { data } = await api.get('/admin/orchestration/tasks');
const rows = Array.isArray(data) ? data : data.data;
if (!Array.isArray(rows)) throw new Error('Invalid orchestration task response');
return rows.map(row => ({ ...row, availableActions: row.availableActions ?? [] }));
},
};
@@ -0,0 +1,31 @@
import {render,screen,fireEvent} from '@testing-library/react';
import {it,expect,vi} from 'vitest';
import api from './api';
import {routerUsage} from './routerUsage';
import RouterUsagePanel from '../components/RouterUsagePanel';
vi.mock('./api',()=>({default:{get:vi.fn()}}));
const metrics={requests:20,inputTokens:100,outputTokens:50,cacheReadTokens:0,cacheWriteTokens:null,reasoningTokens:null,errors:null};
const snapshot={source:'9router',period:'7d',status:'available',reason:null,attribution:{scope:'9router_total',hermes:null,additive:false},freshness:{retrievedAt:'2026-10-22T12:00:00Z',sourceUpdatedAt:null,stale:null},data:{totals:metrics,providers:[{provider:'provider-a',...metrics}],models:[{model:'model-b',provider:'provider-a',...metrics}],accounts:[{accountId:'opaque-1',provider:'provider-a',model:'model-b',...metrics,quota:{status:'unknown',remaining:null,resetAt:null,reason:'upstream_quota_get_mutates_credentials'}}]}};
it('renders concrete backend contract, unknown quota and source freshness; period selects backend filter',async()=>{
vi.mocked(api.get).mockResolvedValue({data:snapshot});render(<RouterUsagePanel/>);
expect(await screen.findByText('opaque-1')).toBeInTheDocument();
expect(screen.getByText('Gateway totals (includes Hermes)')).toBeInTheDocument();
expect(screen.getByText('Hermes attribution: Unknown — not reported; do not add to gateway totals.')).toBeInTheDocument();
expect(screen.getByText('9router')).toBeInTheDocument();
expect(screen.getAllByText('Unknown — not reported').length).toBeGreaterThan(0);
expect(screen.getAllByText('0').length).toBeGreaterThan(0);
expect(api.get).toHaveBeenCalledWith('/admin/router-usage',{params:{period:'7d'}});
fireEvent.change(screen.getByLabelText('Usage period'),{target:{value:'today'}});
await screen.findByText('opaque-1');
expect(api.get).toHaveBeenLastCalledWith('/admin/router-usage',{params:{period:'today'}});
});
it('rejects missing provenance instead of inventing freshness',async()=>{
vi.mocked(api.get).mockResolvedValue({data:{accounts:[]}});
await expect(routerUsage.snapshot()).rejects.toThrow(/Invalid/);
});
it('shows unavailable configuration honestly and discards arbitrary credential properties',async()=>{
vi.mocked(api.get).mockResolvedValueOnce({data:{...snapshot,status:'unavailable',reason:'not_configured',data:null}});
await expect(routerUsage.snapshot()).rejects.toThrow('not_configured');
vi.mocked(api.get).mockResolvedValueOnce({data:{...snapshot,token:'secret',data:{...snapshot.data,credentials:'secret'}}});
expect(JSON.stringify(await routerUsage.snapshot())).not.toContain('secret');
});
@@ -0,0 +1,20 @@
import api from './api';
export const usagePeriods=['today','24h','7d','30d','60d','all'] as const;
export type UsagePeriod=typeof usagePeriods[number];
export interface UsageCounters {requests:number|null;inputTokens:number|null;outputTokens:number|null;cacheReadTokens:number|null;cacheWriteTokens:number|null;reasoningTokens:number|null;errors:number|null}
export interface UsageRow extends UsageCounters {provider:string|null;model?:string|null;accountId?:string|null;quota?:{status:string;remaining:number|null;resetAt:string|null;reason:string|null}}
export interface RouterUsageSnapshot {source:string;period:UsagePeriod;freshness:{retrievedAt:string|null;sourceUpdatedAt:string|null;stale:boolean|null};attribution:{scope:'9router_total';hermes:null;additive:false};data:{totals:UsageCounters;providers:UsageRow[];models:UsageRow[];accounts:UsageRow[]}}
const count=(v:unknown):number|null=>typeof v==='number'&&Number.isSafeInteger(v)&&v>=0?v:null;
const text=(v:unknown):string|null=>typeof v==='string'?v:null;
function counters(raw:UsageCounters):UsageCounters {
return {requests:count(raw?.requests),inputTokens:count(raw?.inputTokens),outputTokens:count(raw?.outputTokens),cacheReadTokens:count(raw?.cacheReadTokens),cacheWriteTokens:count(raw?.cacheWriteTokens),reasoningTokens:count(raw?.reasoningTokens),errors:count(raw?.errors)};
}
function rows(list:UsageRow[]):UsageRow[]{return list.map(a=>({provider:text(a.provider),model:text(a.model),accountId:text(a.accountId),...counters(a),...(a.quota?{quota:{status:a.quota.status,remaining:count(a.quota.remaining),resetAt:text(a.quota.resetAt),reason:text(a.quota.reason)}}:{})}))}
export const routerUsage={async snapshot(period:UsagePeriod='7d'):Promise<RouterUsageSnapshot>{
const {data:raw}=await api.get('/admin/router-usage',{params:{period}});
const data=raw?.success===true?raw.data:raw;
if(data?.status==='unavailable')throw new Error('Usage unavailable: '+(data.reason??'unknown'));
if(data?.status!=='available'||data.source!=='9router'||!usagePeriods.includes(data.period)||!data.freshness||!data.data||!Array.isArray(data.data.providers)||!Array.isArray(data.data.models)||!Array.isArray(data.data.accounts))throw new Error('Invalid usage snapshot contract');
// Explicit allowlist; never forward raw gateway configuration or arbitrary response properties.
return {source:data.source,period:data.period,freshness:{retrievedAt:text(data.freshness.retrievedAt),sourceUpdatedAt:text(data.freshness.sourceUpdatedAt),stale:typeof data.freshness.stale==='boolean'?data.freshness.stale:null},attribution:{scope:'9router_total',hermes:null,additive:false},data:{totals:counters(data.data.totals),providers:rows(data.data.providers),models:rows(data.data.models),accounts:rows(data.data.accounts)}};
}};