pin: bump Worldtree spec to f1b59f8 (v0.35.16) — cold recall closes end-to-end
Worldtree shipped its half of the union-recall fix: #297 (client-side per-scope-value union recall) + #298/#299 (adopt the bifrost v0.6 scope_any/scope_all wire, v0.35.16). It now emits scope_any on the recall path, pairing with our v0.17.6 provider — cold cross-session recall is closed end-to-end (pending a live re-smoke against a v0.35.16 instance). Re-vendored conversation-api-spec.md + conversation_api.contract.md; 285-commit catch-up (v0.29.0 -> v0.35.16). Diff-reviewed: no client-facing breaking changes for our consumer. - #211 agent-slug rename (saga->echo, actor->mask) — slugs only, we pass --agent - #245 end_user_id persistence + memory-scope resolver (additive) - #187/#188/#219 Tier-3 define/PATCH policy (additive); error codes stable - bifrost binding field + ephemeral_does_not_accept_bifrost 422 now documented (#17 surface) - docs: SPEC-PIN.md pin table + history; bifrost-self-test recall status; persistent-memory No package version bump (docs/pin-only, no ratatoskr code change).
This commit is contained in:
@@ -137,6 +137,68 @@ Sessions are persistent via SQLite. On server restart, existing sessions are
|
||||
loadable from the store (lazy-loaded on first access). In-memory cache is
|
||||
rebuilt on demand, not at startup.
|
||||
|
||||
## Memory-partition scope (#245 / ADR-0011)
|
||||
|
||||
`end_user_id` is the per-end-user memory partition key (distinct from `user_id`,
|
||||
the API-key owner). It is REQUIRED at session-create for Lofn (Tier-1) and Tier-3
|
||||
agents and must survive a store reload, because "remember me next session" is by
|
||||
definition a reload. Memory partition resolution flows through ONE resolver that
|
||||
cannot hand an authenticated session the shared `local_dev` partition.
|
||||
|
||||
- **INV-245-1 (end-user-id-durable)**: `end_user_id` is persisted as a `sessions`
|
||||
table column at create and rehydrated onto the `ConversationSession` on every
|
||||
cache-miss load (`get_session`). A session loaded from the store carries the
|
||||
same `end_user_id` it was created with. Pre-migration rows read as `None`.
|
||||
- **INV-245-2 (end-user-id-threaded-all-tiers)**: the `POST /sessions` handler
|
||||
forwards `body.end_user_id` to `create_session` for EVERY agent, not only
|
||||
Tier-3. (The pre-fix `if tier3_agent_context is not None else None` conditional
|
||||
dropped it for Lofn despite the create gate requiring it.)
|
||||
- **INV-245-3 (no-authenticated-local-dev)**: the two MEMORY partition sites —
|
||||
auto-recall (read) and the ContextPromotion producer (write) — resolve via
|
||||
`memory_scope_for_session`. An authenticated, memory-bearing session (one not
|
||||
carrying the explicit `local_dev` sentinel) NEVER resolves to `local_dev`; a
|
||||
missing `end_user_id` raises `MemoryScopeError`, and because both sites are
|
||||
best-effort (recall is fire-and-forget; the producer is `_run_promotion_safe`),
|
||||
the caller skips memory — it never silently writes to the shared partition.
|
||||
- **INV-245-5 (persona-plane-corrected-by-persistence)**: the three PERSONA-plane
|
||||
sites (`inject_context`, `get_state`, `update_after_turn` — ADR-0008 mood/PAD/
|
||||
valence) keep their `session.end_user_id or "local_dev"` form but are on the
|
||||
main turn path where a raise would break the turn. They are corrected by
|
||||
INV-245-1/2: once `end_user_id` is persisted + threaded, the fallback yields a
|
||||
real partition for authenticated sessions and `local_dev` only for the explicit
|
||||
terminal path. Unifying the persona plane under the resolver (with main-path
|
||||
error semantics) is follow-up, tracked with the #246-adjacent hardening.
|
||||
- **INV-245-4 (terminal-explicit-local-dev)**: the internal terminal transport
|
||||
creates its sessions with `end_user_id="local_dev"` explicitly. `local_dev` is
|
||||
reached only by this positive assertion, never by omission. (External API
|
||||
callers passing `local_dev` are still rejected per #216.)
|
||||
|
||||
```contract
|
||||
FN memory_scope_for_session(session) -> MemoryScope
|
||||
BRIEF: The single authority resolving a session to its memory partition scope.
|
||||
Returns a typed MemoryScope(scope_type, scope_id); scope_type ∈
|
||||
{local_dev, end_user, room, tenant} (only local_dev + end_user active in
|
||||
v1; room/tenant reserved for ADR-0010). Cannot yield local_dev for an
|
||||
authenticated session.
|
||||
PRE: [PRE-001 soft] callers have already gated ephemeral / consumer_defined
|
||||
sessions out (those skip memory before resolution)
|
||||
POST: [POST-001 return_value] end_user_id == "local_dev" -> MemoryScope("local_dev", "local_dev")
|
||||
POST: [POST-002 return_value] end_user_id truthy and != "local_dev" -> MemoryScope("end_user", end_user_id)
|
||||
POST: [POST-003 exception] end_user_id is None/empty -> raise MemoryScopeError (NEVER local_dev)
|
||||
ERRORS:
|
||||
MemoryScopeError -> caller skips memory (best-effort) + emits an audit/log line; turn proceeds
|
||||
STEPS:
|
||||
1. [setup] read euid = session.end_user_id
|
||||
2. [branch] euid == "local_dev" -> RETURN MemoryScope("local_dev", "local_dev") (terminal sentinel)
|
||||
3. [branch] euid truthy -> RETURN MemoryScope("end_user", euid)
|
||||
4. [error_handler] else (None/empty) -> RAISE MemoryScopeError (never silently local_dev)
|
||||
TESTS:
|
||||
end_user_partition [happy,tracer]: session end_user_id="alice" -> MemoryScope("end_user","alice")
|
||||
terminal_local_dev [boundary]: session end_user_id="local_dev" -> MemoryScope("local_dev","local_dev")
|
||||
authenticated_none_raises [boundary]: foundational session end_user_id=None -> raises MemoryScopeError, NOT local_dev
|
||||
isolation_roundtrip [happy]: create_session(end_user_id="alice") write + clear cache + reload + recall isolates from a "bob" session; negative-assert no local_dev write
|
||||
```
|
||||
|
||||
```contract
|
||||
FN ConversationService.startup() -> None
|
||||
BRIEF: Discover agents, build per-agent contexts, initialise shared infrastructure
|
||||
@@ -1658,13 +1720,13 @@ Ephemeral templates are a new agent kind that bypass persona, memory, tools, and
|
||||
**Invariants added by issue #161:**
|
||||
|
||||
- **INV-161-1 (ephemeral-template-bypass)**: For sessions where `session.ephemeral_config is not None`, `PersonaRegistry.inject_context` is NOT called pre-turn; `PersonaRegistry.update_after_turn` is NOT called post-turn; valence side-channel is NOT called; tool list passed to provider is `[]`.
|
||||
- **INV-161-2 (frozen-session-config)**: Once a session is created with an `ephemeral_config` snapshot, subsequent mutations to `agents/saga/config.yaml`, `config/providers.yaml → saga_allowed_models`, or `config/defaults.yaml → saga.default_model` do NOT affect that session's per-turn `system_prompt` or `model`.
|
||||
- **INV-161-2 (frozen-session-config)**: Once a session is created with an `ephemeral_config` snapshot, subsequent mutations to `agents/echo/config.yaml`, `config/providers.yaml → echo_allowed_models`, or `config/defaults.yaml → echo.default_model` do NOT affect that session's per-turn `system_prompt` or `model`.
|
||||
- **INV-161-3 (no-tools-for-ephemeral)**: Tool list passed to the provider for an ephemeral session is `[]` regardless of any `tools:` block in the template's config.yaml.
|
||||
- **INV-161-4 (foundational-flow-unchanged)**: For sessions where `session.ephemeral_config is None`, the per-turn path is bit-identical to pre-#161 — same system_prompt loading, same persona injection, same tool list, same audit-log shape.
|
||||
- **INV-161-5 (config-required-for-ephemeral-create)**: `POST /sessions` against an ephemeral template MUST reject the request with 422 if `config` is missing or fails any validation step.
|
||||
- **INV-161-6 (model-allowlist-enforcement)**: `config.model`, when supplied, MUST be in `saga_allowed_models` at session-create time. When omitted, server resolves to `saga.default_model` (startup-validated to be in the allowlist).
|
||||
- **INV-161-6 (model-allowlist-enforcement)**: `config.model`, when supplied, MUST be in `echo_allowed_models` at session-create time. When omitted, server resolves to `echo.default_model` (startup-validated to be in the allowlist).
|
||||
- **INV-161-7 (full-prompt-in-audit)**: Session-create audit entries for ephemeral sessions include `tier: 2` and `ephemeral_config` (full JSON).
|
||||
- **INV-161-8 (cross-user-isolation)**: A Saga session created by user A is invisible to user B — `GET /sessions/{id}` returns 404.
|
||||
- **INV-161-8 (cross-user-isolation)**: An Echo session created by user A is invisible to user B — `GET /sessions/{id}` returns 404.
|
||||
- **INV-161-9 (foundational-rejects-config)**: `POST /sessions { agent_id: "<foundational>", config: {...} }` returns 422 with `error_code: "foundational_does_not_accept_config"`.
|
||||
- **INV-161-10 (capabilities-public-shape)**: `GET /capabilities` is callable by any authenticated key. The response has `ephemeral_templates` at top-level.
|
||||
- **INV-161-11 (template-kind-immutable-at-runtime)**: The `kind` field on a loaded `AgentContext` is set once at startup and never mutated.
|
||||
@@ -1673,16 +1735,16 @@ Ephemeral templates are a new agent kind that bypass persona, memory, tools, and
|
||||
|
||||
| code | HTTP | trigger |
|
||||
|---|---|---|
|
||||
| `ephemeral_requires_config` | 422 | saga session without `config:` |
|
||||
| `ephemeral_requires_config` | 422 | echo session without `config:` |
|
||||
| `foundational_does_not_accept_config` | 422 | foundational agent with `config:` |
|
||||
| `system_prompt_required` | 422 | `config.system_prompt` missing or null |
|
||||
| `system_prompt_empty` | 422 | `config.system_prompt` whitespace-only |
|
||||
| `system_prompt_too_large` | 422 | > 32768 bytes UTF-8 |
|
||||
| `model_not_allowed` | 422 | model not in `saga_allowed_models` |
|
||||
| `model_not_allowed` | 422 | model not in `echo_allowed_models` |
|
||||
|
||||
**New `AgentContext` fields:** `kind: str = "foundational"`, `saga_allowed_models: list | None`, `saga_default_model: str | None` — populated for ephemeral templates, `None` for foundational agents.
|
||||
**New `AgentContext` fields:** `kind: str = "foundational"`, `echo_allowed_models: list | None`, `echo_default_model: str | None` — populated for ephemeral templates, `None` for foundational agents.
|
||||
|
||||
**Startup failfast:** server refuses to start if `agents/saga/config.yaml` is missing/malformed OR `saga.default_model` is not in `saga_allowed_models`. Raises `ConfigurationError` before binding any port.
|
||||
**Startup failfast:** server refuses to start if `agents/echo/config.yaml` is missing/malformed OR `echo.default_model` is not in `echo_allowed_models`. Raises `ConfigurationError` before binding any port.
|
||||
|
||||
**Function-level contracts for issue #161** are documented in `docs/contracts/issues/161.contract.md`.
|
||||
|
||||
@@ -1704,7 +1766,7 @@ Bifrost allows consumers to expose tools to Worldtree agents. `POST /sessions` a
|
||||
|
||||
- **INV-160-1 (handshake-at-create)**: When `POST /sessions` carries `bifrost: {endpoint_url, ...}`, the handshake completes BEFORE the 201 response. No "create session, handshake later" path in v0.1. Verifiable via test: handshake-failing endpoint → 502; session not in store.
|
||||
- **INV-160-2 (one-connection-per-session)**: Each Bifrost-bound session owns exactly one MCP connection. Two sessions binding to the same `endpoint_url` open two independent connections. No pooling, no sharing.
|
||||
- **INV-160-3 (saga-incompatible)**: A session cannot be both ephemeral (Saga, `kind: "ephemeral"`) AND Bifrost-bound. Session-create rejects with 422 `ephemeral_does_not_accept_bifrost`. Verifiable: `POST /sessions { agent_id: "saga", config: {...}, bifrost: {...} }` → 422.
|
||||
- **INV-160-3 (echo-incompatible)**: A session cannot be both ephemeral (Echo, `kind: "ephemeral"`) AND Bifrost-bound. Session-create rejects with 422 `ephemeral_does_not_accept_bifrost`. Verifiable: `POST /sessions { agent_id: "echo", config: {...}, bifrost: {...} }` → 422.
|
||||
- **INV-160-4 (jwt-bound-to-session-expiry)**: JWT TTL is bound to session expiry — far-future `expires_at` for sessions without a fixed TTL. Re-mint happens only when a re-handshake fires (connection-loss recovery). No standalone JWT-staleness check.
|
||||
- **INV-160-5 (reentrancy-25-per-turn)**: At most 25 successful Bifrost tool invocations per agent turn. The 26th returns `bifrost.reentrancy_cap_exceeded` without contacting the consumer. Counter resets per turn via `BifrostClient.reset_turn_counter()`. Enforced inside `BifrostClient.invoke_tool`.
|
||||
- **INV-160-6 (tool-list-cached-per-session)**: Bifrost tools are fetched once at handshake and cached on `ConversationSession.bifrost_tools`. Per-turn dispatch reads from the cache; never re-fetches mid-session except on connection-loss recovery.
|
||||
@@ -1751,7 +1813,7 @@ class BifrostEndpointOverride(BaseModel):
|
||||
|
||||
1. HTTPS URL check — Pydantic field validator; 422 on miss.
|
||||
2. `bifrost:invoke` scope check — same as session-bound path; 403 on miss.
|
||||
3. Ephemeral session rejection — 422 `ephemeral_does_not_accept_bifrost` when session is Saga (extends INV-160-3).
|
||||
3. Ephemeral session rejection — 422 `ephemeral_does_not_accept_bifrost` when session is Echo (extends INV-160-3).
|
||||
4. Heimdall consumer lookup — 502 `bifrost_consumer_not_found` on miss or unregistered.
|
||||
5. Instantiate a new `BifrostClient` with the override consumer's algorithm + key; set `_jwt_ttl_seconds = 60`.
|
||||
6. `await override_client.connect()` — 502 `bifrost_handshake_failed` on failure.
|
||||
@@ -1789,7 +1851,7 @@ In the `finally` block, `await override_client.disconnect()` is called unconditi
|
||||
|
||||
The conversation API grows a three-tier agent model. Tier 1 is the
|
||||
foundational set (Mimir, Bragi, Leif, ...) wired at startup. Tier 2 is
|
||||
the ephemeral template surface (Saga). Tier 3 is the consumer-defined
|
||||
the ephemeral template surface (Echo). Tier 3 is the consumer-defined
|
||||
class addressed by `<user_id>:<agent_name>` and stored in Heimdall's
|
||||
SQLite `consumer_agents` table.
|
||||
|
||||
@@ -1813,9 +1875,13 @@ SQLite `consumer_agents` table.
|
||||
- **INV-181-5 (agent-name-immutable, Phase 2.0 scope)**: PATCH rejects
|
||||
any payload that includes `agent_name`, returning 422
|
||||
`field_not_mutable` BEFORE the DB lookup.
|
||||
- **INV-181-6 (layer-immutable-in-patch, Phase 2.0 scope)**: PATCH
|
||||
rejects payloads carrying any of `persona`, `motivational`,
|
||||
`valence`, `memory` even when set to `null`.
|
||||
- **INV-181-6 (layer-immutable-in-patch, Phase 2.0 scope; AMENDED #188)**:
|
||||
PATCH rejects payloads carrying any of `persona`, `motivational`,
|
||||
`memory` even when set to `null`, returning `field_not_mutable`.
|
||||
**Amended by #188 (Phase 2.3):** `valence` was moved out of this
|
||||
`field_not_mutable` set — it now returns `layer_deferred` (see
|
||||
INV-188-1), because valence is a not-yet-shipped layer, not a frozen
|
||||
trait. `memory` is rejected wholesale (see INV-188-2).
|
||||
- **INV-181-7 (owner-delete-hard, Phase 2.0 scope)**: `DELETE
|
||||
/agents/<id>` is a hard-delete; bypasses the 24h grace.
|
||||
- **INV-181-8 (cascade-key-scoped, Phase 2.0 scope)**: Key revocation
|
||||
@@ -1881,6 +1947,79 @@ SQLite `consumer_agents` table.
|
||||
through `_publish`, so SSE resume / replay handles them with no
|
||||
special case.
|
||||
|
||||
## Amendment — Suspended-tier license-state gate (issue #174, INV-174-1..9)
|
||||
|
||||
Adds a `suspended` tier with empty scope set to drive license-expiry
|
||||
transitions without destroying user state. Endpoint
|
||||
`POST /admin/users/{user_id}/tier` mutates the tier; the
|
||||
`_http_exception_handler` rewrites `AUTH_SCOPE_DENIED` →
|
||||
`USER_SUSPENDED` for any 403 raised against a non-anonymous caller with
|
||||
an empty scope-set (the suspended-tier defining property). Ships in
|
||||
v0.29.1.
|
||||
|
||||
- **INV-174-1 (closed tier vocabulary)**: `POST /admin/users/{user_id}/tier`
|
||||
validates `body.tier` against the hard-coded set `{anonymous, user, free,
|
||||
pro, admin, suspended}`. Out-of-set values return 422 `invalid_tier`.
|
||||
Vocabulary is NOT derived from `policies.yaml` at runtime — a typo in
|
||||
YAML must not silently expand the accepted set.
|
||||
|
||||
- **INV-174-2 (admin-only mutation)**: endpoint requires
|
||||
`admin.users.write.tier_change` scope. Listed explicitly in admin
|
||||
tier's scope set in `policies.yaml` for grep-discoverability (admin
|
||||
also carries `*` umbrella).
|
||||
|
||||
- **INV-174-3 (tier mutation primitive)**:
|
||||
`UserStore.update_user_tier(user_id, new_tier) -> User` is the storage
|
||||
primitive. Raises `LookupError` for unknown user_id (endpoint converts
|
||||
to 404 `user_not_found`).
|
||||
|
||||
- **INV-174-4 (suspended scope-set is exactly empty)**:
|
||||
`policies.yaml.tiers["suspended"].scopes == []`. The empty set is what
|
||||
makes the auth-denial work for free; the
|
||||
`_http_exception_handler` rewrite uses
|
||||
`ctx.user_id != "anonymous" and not ctx.scopes` as the
|
||||
suspended-detection heuristic since `SecurityContext` deliberately
|
||||
excludes `tier` (per `core/integration/types.py:64`).
|
||||
|
||||
- **INV-174-5 (uniform suspended error code via exception handler)**:
|
||||
The `_http_exception_handler` (registered for `StarletteHTTPException`)
|
||||
intercepts every 403 with `error_code: auth_scope_denied`; if the
|
||||
request's stashed `SecurityContext` has an empty scope-set (and
|
||||
non-anonymous user_id), it rewrites the detail to
|
||||
`{error_code: "user_suspended", message: "Account is suspended."}`.
|
||||
Single seam — covers every existing and future scope-deny site
|
||||
without per-endpoint refactor. The ctx is stashed by
|
||||
`get_security_context` on `request.state.security_context`.
|
||||
|
||||
- **INV-174-6 (/me carve-out)**: `/me` does NOT call `authorize()` and
|
||||
therefore never raises `AUTH_SCOPE_DENIED`. Suspended users with
|
||||
empty scopes reach the /me handler normally and see
|
||||
`{user_id, tier: "suspended", scopes: [], ...}`. Adding a scope check
|
||||
to /me without preserving the suspended-tier visibility would be a
|
||||
contract violation — the carve-out is structural, not coded.
|
||||
|
||||
- **INV-174-7 (audit emission)**: every tier-change attempt emits
|
||||
`conversation_api:admin:user:tier_changed` via `_audit_admin_action`
|
||||
with `actor_user_id`, `target_user_id`, `outcome ∈
|
||||
{success, denied}`, and `extra = {from_tier, to_tier, reason}` for
|
||||
successes; `extra = {reason: <reason_code>}` for denials
|
||||
(`invalid_tier`, `user_not_found`).
|
||||
|
||||
- **INV-174-8 (reversibility via audit replay)**: the user record does
|
||||
NOT carry a `previous_tier` column. Restoration of a suspended user
|
||||
requires reading the audit log to find the most recent
|
||||
`tier_changed` event with `to_tier="suspended"` and replaying its
|
||||
`from_tier` as the new target. Operational responsibility of SEA's
|
||||
billing integration; Worldtree provides only the read (audit log) and
|
||||
write (endpoint) surfaces.
|
||||
|
||||
- **INV-174-9 (no cross-tier session invalidation)**: a tier change for
|
||||
a user with active SSE turns in flight does NOT cancel those turns.
|
||||
The next request after the tier change picks up the new scope-set;
|
||||
in-flight streams complete under the old tier. If SEA needs
|
||||
immediate-cutoff semantics, that requires `disable_user`-style
|
||||
hard-revoke, not a tier change.
|
||||
|
||||
## Amendment — AwaitingLLMFirstToken heartbeat (issue #201, INV-201-1..7)
|
||||
|
||||
Adds a periodic SSE heartbeat event during the gap between
|
||||
@@ -2027,3 +2166,160 @@ Lofn introduces zero net-new persistence surface. No table, no
|
||||
column, no Mimir KB collection. No new audit-event types. Existing
|
||||
session-create / session-revoke audit covers Lofn the same way it
|
||||
covers Mimir / Forseti.
|
||||
|
||||
## Amendment — Tier 3 motivational layer (issue #187, Phase 2.2)
|
||||
|
||||
Activates the `motivational` layer field on `POST /agents/define`, narrowing the
|
||||
Phase 2.0 `layer_deferred` rejection (INV-181-3) to `valence` only. Full FN-level
|
||||
spec at `docs/contracts/issues/187.contract.md`.
|
||||
|
||||
- **INV-187-1 (motivational-activated)**: `POST /agents/define` accepts a non-null
|
||||
`motivational` object `{goals, fears}`; `_tier3_validate_layer_fields` rejects
|
||||
only `valence` now. (Persona + memory were activated in Phase 2.1 / #189.)
|
||||
- **INV-187-2 (define-validation)**: `validate_motivational_define_payload` enforces
|
||||
the documented 422 codes — `motivational_id_collision` (case-sensitive, across
|
||||
goals AND fears), `motivational_goal_invalid_type`,
|
||||
`motivational_salience_out_of_range`, `motivational_description_too_short`
|
||||
(< 20 chars after strip), `motivational_missing_required_field`. Unknown top-level
|
||||
OR nested (per goal/fear) keys → `validation_failed` (sub-models extra-forbid).
|
||||
Stricter than the Tier 1 `validate_motivation` (which only warns on short text).
|
||||
- **INV-187-3 (per-agent-scope)**: motivational is per-agent, NOT
|
||||
per-(agent, end_user) — stored once on the row, identical across all end-users.
|
||||
- **INV-187-4 (immutable-in-patch)**: `PATCH` with `motivational` → 422
|
||||
`field_not_mutable` (already covered by INV-181-6's `_IMMUTABLE_FIELDS` gate).
|
||||
- **INV-187-5 (tier3-render-bridge)**: Tier 3 agents are NOT registered with the
|
||||
`persona_registry`; the stored config rides on the per-session `AgentContext`
|
||||
(`motivational_config`) and is rendered into the prompt per-turn in `stream_turn`
|
||||
via `_append_motivational_context_section`, before the memory-context section.
|
||||
- **INV-187-6 (fear-signal-shape)**: fears carry `trigger_signals`; goals carry
|
||||
`positive_signals` + `negative_signals` (matches the `GoalConfig`/`FearConfig`
|
||||
substrate).
|
||||
- **INV-187-7 (tier-uniformity)**: the render reuses `core.persona.goals.load_goals`
|
||||
+ `render_motivational_context`, so a Tier 3 motivational config produces a
|
||||
byte-identical block to an equivalent Tier 1 `motivation.yaml`.
|
||||
- **INV-187-8 (storage)**: persisted in `consumer_agents.tier3_layers_json` under
|
||||
the `"motivational"` key; round-trips via `ConsumerAgent.motivational`; null/omitted
|
||||
→ `None` (no fabricated defaults; no migration).
|
||||
|
||||
### Audit
|
||||
|
||||
`agents.define` audit `extra` gains `presence_motivational: bool` alongside
|
||||
`presence_persona` / `presence_memory`.
|
||||
|
||||
## Amendment — Tier 3 PATCH mutability policy (issue #188, Phase 2.3)
|
||||
|
||||
Settles which Tier 3 agent fields are editable post-define. #197 deleted the
|
||||
STM tier between this issue's filing (2026-05-19) and its implementation, so the
|
||||
"mutable memory dials" the original issue envisioned no longer exist; the policy
|
||||
collapses to: `system_prompt` + `model` mutable, everything else fixed, with
|
||||
`valence` distinguished from the immutable traits by error code. No new
|
||||
endpoint, no new storage, no new invariant philosophy — a clarification +
|
||||
error-code alignment + audit enrichment over the Phase 2.0 PATCH baseline.
|
||||
|
||||
- **INV-188-1 (valence-deferred-in-patch)**: `PATCH /agents/<id>` carrying a
|
||||
`valence` key (any value, including `null`) → 422 `layer_deferred` with
|
||||
`field: "valence"`, matching define-time (INV-181-3). Rationale: valence is
|
||||
a layer that does not exist yet, not a real-but-frozen trait; `layer_deferred`
|
||||
is the truthful reason and gives consumers ONE code for "valence unavailable"
|
||||
across both define and PATCH. The check precedes the DB lookup (INV-181-5/6
|
||||
ordering), so a `valence` PATCH against a missing agent still 422s, not 404s.
|
||||
- **INV-188-2 (memory-wholesale-immutable-in-patch)**: `PATCH` carrying a
|
||||
`memory` key → 422 `field_not_mutable` with `field: "memory"`, rejected at the
|
||||
WHOLE-field level. No sub-field carve-out exists: `stm_capacity` /
|
||||
`stm_token_budget` are deprecated no-ops post-#197, `allows_world_scope` is
|
||||
create-time-only (toggling it after memory is written breaks scope-visibility
|
||||
invariants — memory scope policy must be fixed before any memory is written),
|
||||
and `embedder_version` is library-pinned. A real LTM tuning dial would warrant
|
||||
a deliberate per-sub-field PATCH contract at that time; pre-splitting for dead
|
||||
fields is not done. NOTE the deliberate define/PATCH asymmetry: `define`
|
||||
accept-and-ignores deprecated `stm_*` (201 + DeprecationWarning per
|
||||
INV-197-19), but `PATCH memory:{...}` rejects wholesale (422). Acceptable
|
||||
transitional artifact; disappears when the shims are removed.
|
||||
- **INV-188-3 (patch-audit-before-after)**: a successful `agents.patch` audit
|
||||
event's `extra.changes` records before/after for each mutated field —
|
||||
`model: {before, after}` (literal values; allowlist enum, not PII) and
|
||||
`system_prompt: {before_bytes, after_bytes}` (byte-length only; raw prompt
|
||||
content is excluded as potential PII, consistent with `emit_consumer_agent_event`'s
|
||||
exclusion rule). `changes` contains only keys for fields actually present in
|
||||
the PATCH payload. `patched_fields` (the Phase 2.0 name list) is retained.
|
||||
- **INV-188-4 (mutable-surface-unchanged)**: the mutable surface stays exactly
|
||||
`system_prompt` + `model` (per INV-181 Phase 2.0). PATCH re-enforces the
|
||||
define-time `system_prompt` byte-cap and `model` allowlist. #188 does NOT add
|
||||
model-swap capability/context-window validation — that gap (a swap to a
|
||||
smaller-context or non-tool model with no re-check of the existing prompt) is
|
||||
tracked as a separate follow-up (#219), not folded here.
|
||||
|
||||
## Amendment — model-assignment advisory warnings (issue #219)
|
||||
|
||||
`POST /agents/define` and `PATCH /agents/<id>` attach a best-effort, **non-
|
||||
blocking** `warnings` array to their 2xx response when the assigned `model`
|
||||
carries metadata risk (smaller context window, unknown window, or an explicit
|
||||
capability downgrade). This is advisory-only by deliberate design: hard
|
||||
rejection was rejected (Heid panel + operator, 2026-05-29) because model
|
||||
metadata coverage is partial (`context_window` is 0/unknown for several
|
||||
allowlisted models; `supports_tools` defaults true), the stored `system_prompt`
|
||||
cap is bytes not tokens, Tier 3 agent rows store no tool/modality usage (tools
|
||||
arrive per-session via Bifrost, so any capability concern is inherently
|
||||
conditional), and runtime already classifies the real failure as
|
||||
`CONTEXT_OVERFLOW`. The warning is a receipt-note for the owner who just made a
|
||||
deliberate change, not a correctness gate.
|
||||
|
||||
- **INV-219-1 (advisory-not-blocking)**: neither define nor PATCH ever rejects
|
||||
on context-window or capability grounds. The allowlist check
|
||||
(`model_not_available`) and `system_prompt` byte-cap are the only model-
|
||||
related *rejections*; everything in #219 is a warning on an otherwise-2xx
|
||||
response. Correctness for over-budget prompts remains the runtime
|
||||
`CONTEXT_OVERFLOW` guard.
|
||||
- **INV-219-2 (bounded-warning-codes)**: the closed code set is exactly —
|
||||
`model_context_window_unknown` (severity `info`): the assigned model's
|
||||
registry `context_window` is `0`/absent; `model_context_window_smaller`
|
||||
(severity `warning`): prior and new model both have known windows and
|
||||
new < prior (`details: {before, after}`); `model_capability_downgrade`
|
||||
(severity `warning`): the new model EXPLICITLY drops a capability the prior
|
||||
model advertised — `supports_tools`, `vision`, or `audio` (`details:
|
||||
{dropped: [...]}`). No token-aware "prompt won't fit" code — deferred until
|
||||
tokenizer-aware estimation exists; messages never claim a hard fit/failure.
|
||||
- **INV-219-3 (when-evaluated, resulting-pair)**: warnings are computed
|
||||
whenever a model is *assigned*. At define, always (prior = None → only
|
||||
`model_context_window_unknown` can apply, since the comparative codes need a
|
||||
prior). At PATCH, only when the payload carries a `model` key whose value
|
||||
differs from the stored model (prior = stored model); a PATCH without `model`
|
||||
(e.g. `system_prompt`-only) emits no model warnings. The comparison is always
|
||||
against the *resulting* model.
|
||||
- **INV-219-4 (capability-downgrade)**: a `model_capability_downgrade` fires
|
||||
only when BOTH prior and new models resolve to registry `ModelInfo` AND the
|
||||
new model's *effective* capability flags lack one the prior advertised
|
||||
(`supports_tools`, `vision`, or `audio`). The "both resolve" guard is the
|
||||
false-positive defense — an unresolvable model on either side yields no
|
||||
downgrade claim. Beyond that, comparison uses the registry's **effective**
|
||||
flags, which is asymmetric by capability because the data model collapses
|
||||
absent-to-default and does not preserve a "was this declared?" bit:
|
||||
- `supports_tools` defaults **true** (`ModelInfo` / `_build_model_info`), so
|
||||
a tools-drop requires the new catalog entry to set `supports_tools: false`
|
||||
*explicitly* — omission never triggers it.
|
||||
- `vision` / `audio` default **false** (`ModelCapabilities`), so a drop is
|
||||
detected whenever the prior advertised the capability and the new model does
|
||||
not carry it — whether the new entry says `false` explicitly OR omits it.
|
||||
This is the deliberate conservative reading: an undeclared modality is
|
||||
treated as unsupported. (A vision-capable model with sloppy metadata that
|
||||
omits its `vision` flag would thus be reported as a downgrade; the remedy is
|
||||
to declare the flag in the catalog, not to suppress the advisory.)
|
||||
|
||||
Message phrasing is conditional ("if your sessions rely on these, e.g. Bifrost
|
||||
tools, they may be rejected") — the agent row does not record whether tools or
|
||||
modalities are actually used, so every capability warning is advisory by
|
||||
nature.
|
||||
- **INV-219-5 (inline-response-shape)**: the `warnings` array is added inline to
|
||||
the define (201) and PATCH (200) response bodies — the existing flat
|
||||
`ConsumerAgentResponse` dict gains a `warnings` key (always present, `[]` when
|
||||
none). It is NOT added to the shared `ConsumerAgentResponse` pydantic model
|
||||
nor to `GET /agents/<id>` — only the two mutation handlers merge it into their
|
||||
returned dict, keeping persisted fields and the read path unchanged. Each
|
||||
entry is `{code, severity, message, details}`.
|
||||
- **INV-219-6 (single-helper)**: a single pure helper
|
||||
`compute_model_swap_warnings(*, prior_model: str | None, new_model: str,
|
||||
registry)` is the only source of warning logic; both define and PATCH call
|
||||
it. It tolerates unresolvable specs / `None` `ModelInfo` / `context_window`
|
||||
`0` by treating them as "unknown" (emitting the unknown-window info code where
|
||||
applicable, never raising). Metadata improvements over time sharpen the
|
||||
warnings with no API or signature change.
|
||||
|
||||
Reference in New Issue
Block a user