feat(clients): sessions+registry+optimize+armor: close gaps, loud list truncation, shared Gemini adapter
sessions: operations get/list/cancel/delete/wait for engine, session, memory and serving profile; servingProfiles CRUD. registry: ListResult with truncated flag, v1alpha twins, gateway/policy operations, authz IAM, deny policy update, boundary patch/bindings. optimize: make_gemini_model over models::VertexModel (DirectModel removed), generateSyntheticData, online evaluator operations, trace/log writers. armor: SecurityAdmin for all SCC v2 methods (attack exposure excluded), documented agent threat categories, floor settings fixed to location global after live run. check_discovery.py of all four enforce coverage. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
+59
-18
@@ -17,8 +17,16 @@ Gemini Enterprise Agent Platform, Agent Engine (`reasoningEngines`) children:
|
||||
create, get, list, patch, delete, purge (explicit, guarded), revisions
|
||||
(list, get), rollback, topics (managed and custom), scope maps, metadata.
|
||||
- Long-running operations: every mutating call returns an Operation; the module
|
||||
waits with `wait_operation` (hard caps in `OperationCaps`). `operation()`,
|
||||
`cancel_operation()` and `wait()` expose them for one engine only.
|
||||
waits with `wait_operation` (hard caps in `OperationCaps`). All five
|
||||
Discovery operations methods (get, list, cancel, delete, wait) are wrapped
|
||||
for the four places Discovery puts them: under the engine, under a session,
|
||||
under a memory and under a serving profile (20 table rows). `operation()`,
|
||||
`list_operations()`, `cancel_operation()`, `delete_operation()`, `wait()`
|
||||
(client polling) and `wait_server()` (one POST `:wait?timeout=Ns`, 1..60 s)
|
||||
work for one root only: the engine, or the location for serving profiles.
|
||||
- Serving profiles (`projects.locations.servingProfiles`, location level, not
|
||||
engine scoped): create (waits), get, list, patch, delete, with scope
|
||||
`GEMINI_LIVE`, `INTERACTIONS_API` or `RESPONSE_API`, optional CMEK key.
|
||||
|
||||
Everything is against one API surface: `aiplatform` **v1beta1**. See section 6
|
||||
for why not v1.
|
||||
@@ -29,15 +37,18 @@ for why not v1.
|
||||
|---|---|
|
||||
| `caps.h` | Static ceilings (`SessionsCaps`, `MemoryCaps`) |
|
||||
| `calls.h` | The ONE table of every REST call (verb, path, discovery method, request fields, query params) |
|
||||
| `names.h/.cpp` | `EngineName` (validated resource name), `Check` (input validators), wire helpers |
|
||||
| `names.h/.cpp` | `EngineName`, `LocationName` (validated resource names), `Check` (input validators), wire helpers |
|
||||
| `operation_names.h/.cpp` | `OperationName`: validates an operation name against its root, picks the table row for each verb by owner (engine, session, memory, serving profile) |
|
||||
| `operation_service.h/.cpp` | `OperationService : Service`: table-driven `send`, `settle`, loud capped `list_items` (`list_over_limit`), the operations surface |
|
||||
| `serving_profile.h/.cpp` | `ServingProfileSpec`, `ServingProfilePatch`, `ServingProfile`, `ServingScope`, `ServingProfiles : OperationService` |
|
||||
| `session_types.h/.cpp` | `SessionSpec`, `Session`, `SessionPatch`, `CompactRequest`, `SessionEvent`, list options |
|
||||
| `memory_types.h/.cpp` | `Memory`, `MemorySpec`, `MemoryPatch`, `Topic`, `MetadataValue`, `MetadataFilter`, `MemoryGenerateRequest`, `IngestRequest`, `RetrieveRequest`, `PurgeRequest`, `MemoryRevision`, `Profile` |
|
||||
| `engine_service.h/.cpp` | `EngineService : Service`: table-driven `send`, `settle`, capped `list_items`, operation helpers |
|
||||
| `engine_service.h/.cpp` | `EngineService : OperationService`: one validated engine and its v1beta1 endpoint |
|
||||
| `sessions.h/.cpp` | `Sessions : EngineService` |
|
||||
| `memory_bank.h/.cpp` | `MemoryBank : EngineService` |
|
||||
| `tools/check_discovery.py` | Verifies `calls.h` and the typed bodies against Google's Discovery document |
|
||||
|
||||
Tests: `tests/src/google/sessions/test_sessions.cpp`. Example:
|
||||
Tests: `tests/src/google/sessions/test_sessions.cpp` and `test_sessions_gaps.cpp`. Example:
|
||||
`example/app/agent/SessionsDemo.cpp` (routes under `/agent/sessions`), tests in
|
||||
`tests/example/agent/sessions/`.
|
||||
|
||||
@@ -50,7 +61,9 @@ Tests: `tests/src/google/sessions/test_sessions.cpp`. Example:
|
||||
| Session TTL | `Ns` form, 24 h minimum (Google), 3650 days maximum (ours) |
|
||||
| session_state / event | 64 KiB / 256 KiB serialized |
|
||||
| Labels | 20, key and value 64 chars |
|
||||
| List pages / items | 10 pages of 100, 1000 items; more is `RESULT_TOO_LARGE`, narrow the filter |
|
||||
| List pages / items | 10 pages of 100, 1000 items; more items OR a further page after the last allowed one is `RESULT_TOO_LARGE` (502), never a silent cut, narrow the filter |
|
||||
| Server-side operation wait | 1..60 s per call (`kMaxServerWaitSeconds`) |
|
||||
| Serving profile | id 1..63 `[a-z0-9-]`, display name required 128, description 4000, KMS key name 512 |
|
||||
| Scope | 1..10 entries, 128 chars, no `*` |
|
||||
| Fact / description / context | 4000 chars |
|
||||
| Generate sources | 100 events, 64 KiB; direct memories max 5 (Google) |
|
||||
@@ -83,10 +96,14 @@ Tests: `tests/src/google/sessions/test_sessions.cpp`. Example:
|
||||
credential) and fails if a declared call, verb, path, request field, query
|
||||
parameter, enum value, response key or nested request field is absent.
|
||||
|
||||
Result 2026-10-24: `OK 2026-10-24: 23 calls, 7 enums, 25 response keys, 18
|
||||
nested schemas match aiplatform v1beta1 discovery`. A deliberately misspelled
|
||||
field made it exit 1 (checked). Rerun it after any change to `calls.h` or the
|
||||
typed bodies.
|
||||
Result 2026-10-24: `OK 2026-10-24: 46 calls, 8 enums, 34 response keys, 20
|
||||
nested schemas match aiplatform v1beta1 discovery`. The script also checks
|
||||
coverage: every Discovery method under `reasoningEngines.operations`,
|
||||
`reasoningEngines.sessions`, `reasoningEngines.memories` and `servingProfiles`
|
||||
must be a table row or listed in `EXCLUDED` (empty: nothing is excluded), so a
|
||||
method Google adds later fails the check. A deliberately misspelled field made
|
||||
it exit 1 (checked). Rerun it after any change to `calls.h` or the typed
|
||||
bodies.
|
||||
|
||||
From discovery (v1beta1, `projects.locations.reasoningEngines`):
|
||||
sessions create (POST, `sessionId` query, returns Operation), get, list
|
||||
@@ -95,9 +112,12 @@ Operation), appendEvent (POST `:appendEvent`, body `SessionEvent`), compact
|
||||
(POST `:compact`, returns Operation), events.list (`sessionEvents`);
|
||||
memories generate / retrieve / retrieveProfiles / create (`memoryId`) / get /
|
||||
list / patch (`updateMask`) / delete / purge / rollback / ingestEvents,
|
||||
memories.revisions list / get; operations get / cancel. Discovery also lists
|
||||
`wait`, `list`, `delete` on operations, which this module does not wrap
|
||||
(`wait_operation` polls with GET).
|
||||
memories.revisions list / get; operations get / cancel / list / delete / wait
|
||||
under the engine, `sessions.operations.*` and `memories.operations.*` (same
|
||||
five), `locations.servingProfiles` create (`servingProfileId` query, returns
|
||||
Operation) / get / list / patch (`updateMask`) / delete (returns Empty) and
|
||||
`servingProfiles.operations.*`. The Method column of a `calls.h` row is
|
||||
relative to `kDiscoveryPrefix` unless it starts with `aiplatform.`.
|
||||
|
||||
## 6. Verified live
|
||||
|
||||
@@ -127,6 +147,20 @@ an express key and a token; v1 refuses keys. The opt-in test `sessions_live`
|
||||
the real client (sessions list / get / events, memories list / get /
|
||||
revisions) and passed with the key and with the token on 2026-10-24.
|
||||
|
||||
Gap-closing round, same day, service-account token, read-only:
|
||||
|
||||
| Call | Result |
|
||||
|---|---|
|
||||
| GET `v1beta1/.../reasoningEngines/1/operations?pageSize=5`, `.../sessions/abc/operations`, `.../memories/abc/operations` | 200 `{}` (empty list, even though engine 1 does not exist) |
|
||||
| GET `v1beta1/.../locations/us-central1/servingProfiles?pageSize=5` (also `global` host and `europe-west4`) | 501 `UNIMPLEMENTED` "Operation is not implemented, or supported, or enabled." (not available to this project) |
|
||||
| GET `v1beta1/.../servingProfiles/probe` | 501 UNIMPLEMENTED |
|
||||
| GET `v1beta1/.../servingProfiles/probe/operations` | 400 INVALID_ARGUMENT: "the idType servingProfiles is not a documented LRO Parent ID, the associated value must be a Long, but was instead: probe" |
|
||||
| GET `v1beta1/.../servingProfiles/123/operations?pageSize=1` | 200 `{}` |
|
||||
|
||||
The opt-in test `sessions_live.operations_and_serving_profiles_reads` repeats
|
||||
the operations lists and the servingProfiles list through the real client; it
|
||||
accepts 200 or 501/403/404 for servingProfiles and prints which one it saw.
|
||||
|
||||
No Agent Engine exists in the project, so **no happy path was verified
|
||||
live**: create, patch, delete, append, compact, generate, ingest, retrieve,
|
||||
retrieveProfiles, purge, rollback are verified by discovery only. Nothing that
|
||||
@@ -151,18 +185,25 @@ Neither discovery nor the docs pages read state these; they are inferred:
|
||||
search model (docs); the error body when it is not is unread.
|
||||
- Memory Profiles need schema configs on the engine (`MemoryBankConfig` in the
|
||||
runtime module); the shape of `profile` is free-form and kept raw.
|
||||
- Serving profile id charset (`[a-z0-9-]`, 1..63 is our choice) and the real
|
||||
id rule: Google's LRO layer wants a numeric id for operations under a
|
||||
serving profile (400 above), so Google may assign or require numeric ids.
|
||||
The create/patch responses (Operation `response` is `Any`) are parsed
|
||||
tolerantly with a GET fallback. `servingProfiles` itself answers 501 on this
|
||||
project, so no body of it was ever seen.
|
||||
- Whether `operations.wait` answers `done: false` at the timeout or an error
|
||||
(the docs line says "at most the time permitted"): both are handled, a
|
||||
not-done answer is returned to the caller, not retried.
|
||||
- Managed topic names beyond the four in discovery, and `thought`/`audio` parts
|
||||
inside event `content` (typed by `gemini_types.h`, unknown parts dropped).
|
||||
|
||||
## 8. Gaps
|
||||
|
||||
- `servingProfiles` (location-level create/get/list/patch for Gemini Live,
|
||||
Interactions and Response APIs) is listed by discovery next to this product
|
||||
but is not engine-scoped; not implemented here. Owner: the `live` or
|
||||
`models` module.
|
||||
- Engine-level Memory Bank configuration (`contextSpec.memoryBankConfig`,
|
||||
customization, TTL config) is part of the Agent Engine resource: runtime
|
||||
module.
|
||||
- Operations `list`, `delete`, `wait` (server-side) are not wrapped.
|
||||
- `servingProfiles` answers 501 for the test project in three locations, so
|
||||
the happy path is Discovery-verified only. Owner: a project that has the
|
||||
feature; test `sessions_live.operations_and_serving_profiles_reads`.
|
||||
- Session and memory `labels` / `metadata` filters beyond a passthrough string.
|
||||
- Token refresh is the caller's job (foundation gap).
|
||||
|
||||
Reference in New Issue
Block a user