diff --git a/frontend/admin-panel/V4_PANEL_COMPLETION_CONTRACT.md b/frontend/admin-panel/V4_PANEL_COMPLETION_CONTRACT.md new file mode 100644 index 00000000..f0635436 --- /dev/null +++ b/frontend/admin-panel/V4_PANEL_COMPLETION_CONTRACT.md @@ -0,0 +1,33 @@ +# Admin v4 completion integration contract + +Frontend-only slice based on 5507fbc. No deployment or runtime writes. The historical read-only integration document does not authorize enabling routes. Backend policy remains the authority; UI adds deny-only safety restrictions, never permissions. + +## Workflow (existing routes retained) + +- GET `/admin/orchestration/overview`: ResourceSnapshot with `items`, ISO `measuredAt`, `capabilities:{mutations:boolean,chat:boolean,runtime:boolean}`. Missing/failed capability read defaults false. +- GET `/admin/orchestration/tasks`: Task[] (or `{success:true,data:Task[]}`). +- GET `/admin/orchestration/tasks/:id`: Task. Required identity/version/state/mode/budget and server-computed `availableActions`; optional scope/acceptance metadata, runs/artifacts, immutable decisions, events and budgetLedger. Missing actions means no permission. Include structured redacted scope metadata for a useful Gate1 review; no secrets or arbitrary event payloads. +- POST `/admin/orchestration/tasks`: existing CreateTaskInput `{key,title,department,operationMode,budgetLimitCents,metadata:{scope,acceptanceCriteria:string[]}}`. UI allows OBSERVE/PREPARE only, not Production. Key is unique business identity; after an ambiguous create, reconcile key before resubmission. Success locks the form to prevent accidental duplicate submission. +- PUT `/admin/orchestration/tasks/:id/transition`: TransitionDto `{toState,expectedVersion,idempotencyKey,reason}`. +- POST `/admin/orchestration/tasks/:id/gates/:gate/decide`: GateDecisionDto `{decision:'APPROVED'|'REJECTED',expectedVersion,idempotencyKey,expiresAt,notes}`; Gate2 approval additionally binds `{runId,artifactHash,commitSha,environment}` from a registered SUCCEEDED run, never editable commit/environment. Gate1 is bounded work, not release permission. +- ServerAction `{id,label,toState? ,gate?:1|2,decision?:'APPROVED'|'REJECTED',disabledReason?}`. Exactly one of transition or gate decision. All role/policy/kill/version checks remain backend-side. Browser identity fields are never posted; actor must derive from verified JWT. HOLD/request changes only appear if advertised as supported transitions. EDIT_AND_APPROVE is unavailable without a separately reviewed DTO; no guessed mutation endpoint. +- HTTP409 stale version/idempotency mismatch, 410 expired, 401/403 denied and other 4xx permanently lock that dialog; refresh and review afresh. Network/5xx ambiguous failures allow only identical payload/key. Inputs and navigation are locked after first attempt; authoritative refresh invalidates selection and pending detail reads. No optimistic status update. +- Production task actions and release transitions remain disabled even if advertised. Gate2 evidence inspection is not deployment authorization. Server still enforces TTL; browser time is a usability check, not trusted authorization. + +## Runtime read API (aligned by read-only inspection with runtime sibling) + +Uses existing JWT Axios client, never upstream Hermes paths or tokens. No automatic runtime mutations. Tab is explicitly selected; failed auth/config/routes show unavailable. + +- GET `/admin/orchestration/runtime/health` -> `{ok:boolean,version:string,commit:string,auth_required:true}`. Any false/missing authentication flag is rejected. +- GET `/admin/orchestration/runtime/profiles` -> `{name:string,is_default:boolean,gateway_running:boolean}[]`, already filtered to principal grants. +- GET `/admin/orchestration/runtime/status?profile=` -> `{version,gateway_running,overall,active_agents,gateway_state:string|null}`. +- GET `/admin/orchestration/runtime/sessions?profile=&limit=20&offset=0` -> `{total:number,sessions:{id,profile,source,is_active}[]}`. UI paginates; profile mismatch is rejected. +- GET `/admin/orchestration/runtime/usage?profile=&days=30` -> `{period_days:number,totals:{total_input,total_output,total_sessions,total_estimated_cost}}`. + +Runtime client explicitly projects known fields; unknown secret fields are discarded. Numeric zero survives. Cost is labelled **upstream estimate**, unspecified currency, not settled billing and never added to overlapping 9router totals. Client observation time is not server heartbeat/freshness. Profile gateway flags and active agent count are source observations, not invented readiness/department counts. Generic Resources for existing agents/model-policy/schedules/releases remain unchanged; unavailable contracts stay visibly unavailable. Runtime schedules/model-info may exist backend-side but are not guessed into generic Resources. + +## Verification + +Runner: disposable node:22-bookworm, --userns=host --network none; source and dependency donor read-only, private copies in /work. No donor/source build writes. Required final gates: `tsc --noEmit -p tsconfig.app.json`, `npm run build`, `npm test -- --maxWorkers=2`. Logs under `/opt/services/canina/validation/v4-panel-completion/` (outside discovery). Earlier RED proves 7 workflow failures and 2 selection/idempotency failures; runtime RED is missing new component. Existing test fixtures migrated from invented VERIFIED run status to backend SUCCEEDED status. No tests skipped or permissions inferred. + +Not claimed: live backend browser acceptance, real authenticated runtime availability, Stage publication, CI evidence authority or Production execution. Parent owns integration and publication. diff --git a/frontend/admin-panel/src/components/CreateOrchestrationTask.tsx b/frontend/admin-panel/src/components/CreateOrchestrationTask.tsx index 0201f476..1931041a 100644 --- a/frontend/admin-panel/src/components/CreateOrchestrationTask.tsx +++ b/frontend/admin-panel/src/components/CreateOrchestrationTask.tsx @@ -6,9 +6,9 @@ export default function CreateOrchestrationTask({onCreated}:{onCreated:()=>void} const [fields,setFields]=useState({key:'',title:'',department:'',scope:'',criteria:'',budget:''}); const [mode,setMode]=useState('PREPARE');const [busy,setBusy]=useState(false);const [error,setError]=useState('');const [success,setSuccess]=useState(''); const valid=Object.values(fields).every(value=>value.trim())&&Number.isSafeInteger(Number(fields.budget))&&Number(fields.budget)>=0; - return
Create bounded work
{e.preventDefault();if(!valid||busy)return;setBusy(true);setError('');setSuccess('');try{await orchestration.create({key:fields.key,title:fields.title,department:fields.department,operationMode:mode,budgetLimitCents:Number(fields.budget),metadata:{scope:fields.scope,acceptanceCriteria:fields.criteria.split('\n').map(s=>s.trim()).filter(Boolean)}});setSuccess('Task created by backend.');onCreated()}catch(error){setError(error instanceof Error?error.message:'Create failed; reconcile task key before retry')}finally{setBusy(false)}}}> - {([['key','Task key'],['title','Title'],['department','Department'],['scope','Bounded scope'],['criteria','Acceptance criteria (one per line)'],['budget','Budget cap in cents']] as const).map(([key,label])=>