feat(cloud): add targeted task governance foundation

2026-07-13 22:21:12 +08:00
parent a3ba94be04
commit 2cd314b183
41 changed files with 2099 additions and 15 deletions
@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Cloud-proxied planner calls produce durable non-secret usage events
+After the Cloud planner proxy resolves a provider call, the system SHALL record
+a durable usage event with Host, provider/model, provider-reported token
+counts, request outcome, and known task-attempt context, while excluding raw
+prompts, screenshots, provider credentials, cookies, and lease secrets.
+
+#### Scenario: Provider returns token usage
+- **WHEN** a Cloud-proxied planner call completes with provider-reported token
+  counts
+- **THEN** the system stores those counts against the authenticated Host and
+  returns the planner decision without exposing secret request content
+
+#### Scenario: Assignment context is available
+- **WHEN** the Host makes a proxied planner call while executing a claimed
+  assignment
+- **THEN** the recorded event includes that task id and attempt identifier
+
+### Requirement: Host token budgets use atomic reservation and settlement
+The Cloud planner proxy SHALL atomically reserve a conservative per-call token
+amount before a provider invocation for every Host with an effective AI token
+budget using Cloud planner transport, SHALL reject over-budget calls before
+invoking the provider, and SHALL settle the reservation to provider-reported
+usage when available.
+
+#### Scenario: Remaining budget permits a call
+- **WHEN** used tokens plus active reservations and the next conservative
+  reservation are within the Host's UTC-day budget
+- **THEN** the proxy reserves budget, invokes the provider, and settles the
+  reservation after the provider response
+
+#### Scenario: Remaining budget is insufficient
+- **WHEN** the next reservation would exceed the Host's effective budget
+- **THEN** the proxy rejects the planner call without invoking the provider
+
+#### Scenario: Provider outcome has unknown usage
+- **WHEN** a transport failure prevents the proxy from determining actual
+  provider usage after reservation
+- **THEN** the reservation remains active until bounded expiry cleanup rather
+  than being released optimistically
+
+### Requirement: Direct planner transport is explicitly unmetered
+The system SHALL represent a Host using direct-to-provider planner transport as
+unmetered for Cloud token accounting and SHALL not report it as complying with
+a Cloud-enforced token budget.
+
+#### Scenario: Console inspects a direct-transport Host
+- **WHEN** an authorized operator views AI usage for a Host not using Cloud
+  planner transport
+- **THEN** the system reports the Host as unmetered rather than zero usage or
+  hard-budget-enforced