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:
+142
-21
@@ -61,7 +61,7 @@ When you call `POST /sessions` against an agent, the authorization check that fi
|
||||
|
||||
### Tier 1 — foundational agents (no `:` in agent_id)
|
||||
|
||||
Agents bundled with Worldtree: `mimir`, `lofn`, `soong`, `forseti`, `domari`, `vili`, `actor`, `saga`, `bragi`, `leif`, `troi`, `cara`, `glados`, and any future Asgardian. The agent_id is a simple slug like `mimir` — no colon.
|
||||
Agents bundled with Worldtree: `mimir`, `lofn`, `forseti`, `domari`, `vili`, `mask`, `echo`, `muninn`, and any future Asgardian. The agent_id is a simple slug like `mimir` — no colon.
|
||||
|
||||
> **About tiers:** Your `tier` is set on the `users` table row your API key resolves to, assigned at key-mint time (see `POST /admin/keys`). Tiers are `anonymous` (dev-mode unauthenticated), `user` (default for newly-issued keys), `free`/`pro` (subscription-shaped, not actively differentiated), and `admin`. The tier you have is visible via `GET /me`'s `tier` field. Tier-derived scopes come from `config/policies.yaml > tiers.<tier>.scopes` — there is no per-key scope override.
|
||||
|
||||
@@ -989,7 +989,7 @@ Create a new conversation session with an agent.
|
||||
**Bifrost field validation:**
|
||||
- `endpoint_url`: required, must be an HTTPS URL.
|
||||
- `scope`: optional, ≤ 256 chars, opaque string passed through to the JWT payload unchanged.
|
||||
- Bifrost binding is **incompatible with ephemeral (Saga) sessions** — returns 422 `ephemeral_does_not_accept_bifrost`.
|
||||
- Bifrost binding is **incompatible with ephemeral (Echo) sessions** — returns 422 `ephemeral_does_not_accept_bifrost`.
|
||||
- Requires the `bifrost:invoke` scope (included in the `user` tier by default).
|
||||
|
||||
**Response:** `201 Created`
|
||||
@@ -1535,7 +1535,7 @@ for (const tc of items) {
|
||||
|
||||
Ephemeral templates are a second tier of agent, distinct from foundational persistent agents (Mimir, Soong, etc.). They have no persona, no memory, no tools, and no motivational context. The consumer supplies the system prompt and (optionally) the model at session-create time; that config is frozen for the session's lifetime.
|
||||
|
||||
**Saga** is the first ephemeral template — Norse goddess of history and chronicle, a blank-slate actor that becomes whatever the consumer's system prompt instills.
|
||||
**Echo** is the first ephemeral template — a blank-slate per-session host that becomes whatever the consumer's system prompt instills.
|
||||
|
||||
### Discovering available templates
|
||||
|
||||
@@ -1547,7 +1547,7 @@ Authorization: Bearer <any valid key>
|
||||
```json
|
||||
{
|
||||
"ephemeral_templates": {
|
||||
"saga": {
|
||||
"echo": {
|
||||
"allowed_models": ["glm5-turbo", "glm4.7", "glm4.5-air", "granite-structured", "qwen3.6-35-a3b"],
|
||||
"default_model": "glm5-turbo",
|
||||
"system_prompt_max_bytes": 32768
|
||||
@@ -1556,14 +1556,14 @@ Authorization: Bearer <any valid key>
|
||||
}
|
||||
```
|
||||
|
||||
`GET /capabilities` does not require `instantiate:saga` scope — any authenticated caller can read what's available before deciding to instantiate.
|
||||
`GET /capabilities` does not require `instantiate:echo` scope — any authenticated caller can read what's available before deciding to instantiate.
|
||||
|
||||
### Creating an ephemeral session
|
||||
|
||||
```json
|
||||
POST /sessions
|
||||
{
|
||||
"agent_id": "saga",
|
||||
"agent_id": "echo",
|
||||
"config": {
|
||||
"system_prompt": "You are a careful, skeptical frame-clarifier...",
|
||||
"model": "glm5-turbo"
|
||||
@@ -1580,16 +1580,16 @@ POST /sessions
|
||||
| `system_prompt_required` | `config.system_prompt` missing or null |
|
||||
| `system_prompt_empty` | `config.system_prompt` is whitespace-only |
|
||||
| `system_prompt_too_large` | `config.system_prompt` > 32768 bytes UTF-8 |
|
||||
| `model_not_allowed` | `config.model` present but not in `saga_allowed_models` |
|
||||
| `model_not_allowed` | `config.model` present but not in `echo_allowed_models` |
|
||||
|
||||
**`config.model` resolution:** When `config.model` is omitted (or `null`), the server resolves it to `saga.default_model` from `config/defaults.yaml`. The resolved value is always populated in the session snapshot; `model` is never left absent or null in the stored config.
|
||||
**`config.model` resolution:** When `config.model` is omitted (or `null`), the server resolves it to `echo.default_model` from `config/defaults.yaml`. The resolved value is always populated in the session snapshot; `model` is never left absent or null in the stored config.
|
||||
|
||||
**Response:** Same 201 shape as foundational sessions, with two new fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "...",
|
||||
"agent_id": "saga",
|
||||
"agent_id": "echo",
|
||||
"kind": "ephemeral",
|
||||
"config": {
|
||||
"system_prompt": "You are a careful, skeptical frame-clarifier...",
|
||||
@@ -1601,7 +1601,7 @@ POST /sessions
|
||||
}
|
||||
```
|
||||
|
||||
**`kind` field:** `"ephemeral"` for Saga sessions, `"foundational"` for all other sessions. Present on both `GET /sessions` list items and `GET /sessions/{id}`.
|
||||
**`kind` field:** `"ephemeral"` for Echo sessions, `"foundational"` for all other sessions. Present on both `GET /sessions` list items and `GET /sessions/{id}`.
|
||||
|
||||
### Sending messages to an ephemeral session
|
||||
|
||||
@@ -1617,9 +1617,9 @@ SSE, cancel, `persist_partial`, rate limits, and error shapes are bit-identical
|
||||
|
||||
### Scope
|
||||
|
||||
Creating a Saga session requires the `instantiate:saga` scope. This scope is bundled in the `user` tier. Tier `admin` inherits it via the wildcard.
|
||||
Creating an Echo session requires the `instantiate:echo` scope. This scope is bundled in the `user` tier. Tier `admin` inherits it via the wildcard.
|
||||
|
||||
### What Saga does NOT do
|
||||
### What Echo does NOT do
|
||||
|
||||
- No persona injection (`PersonaRegistry.inject_context` not called)
|
||||
- No post-turn appraisal (`PersonaRegistry.update_after_turn` not called)
|
||||
@@ -2415,7 +2415,7 @@ The `POST /sessions/{session_id}/messages` endpoint also accepts an additive `mo
|
||||
- Override is per-call only. Stored `CharacterSchema.model` is NOT mutated.
|
||||
- Validated against the same `available_for_characters` allowlist that gates `CharacterSchema.model` at create time (#153 INV-091).
|
||||
- Override displaces the character's bound model when both are set (per-call wins).
|
||||
- Override is REJECTED on ephemeral (Saga) sessions — their config is frozen at session-create per INV-161-2.
|
||||
- Override is REJECTED on ephemeral (Echo) sessions — their config is frozen at session-create per INV-161-2.
|
||||
|
||||
**Validation:**
|
||||
1. Pydantic validates `model`: optional string, non-empty after stripping whitespace.
|
||||
@@ -2672,7 +2672,7 @@ The override client has a fresh 25-call reentrancy budget, independent of the se
|
||||
| Condition | HTTP | `error_code` | `bifrost_error` |
|
||||
|-----------|------|-------------|----------------|
|
||||
| `endpoint_url` is not HTTPS | 422 | `validation_failed` | — |
|
||||
| Ephemeral (Saga) session | 422 | `validation_failed` | — |
|
||||
| Ephemeral (Echo) session | 422 | `validation_failed` | — |
|
||||
| Missing `bifrost:invoke` scope | 403 | `auth_scope_denied` | — |
|
||||
| `consumer_id` not in Heimdall or not Bifrost-registered | 502 | `bifrost_consumer_not_found` | — |
|
||||
| Handshake failed (network, auth, etc.) | 502 | `bifrost_handshake_failed` | spec error code |
|
||||
@@ -2753,6 +2753,61 @@ Caller must:
|
||||
`agent_name` is a strict slug `[a-z][a-z0-9-]{2,63}` and immutable
|
||||
after definition.
|
||||
|
||||
The 201 response includes an advisory `warnings` array (#219) — see
|
||||
"Model-assignment warnings" under `PATCH` below.
|
||||
|
||||
##### Motivational layer (Phase 2.2, #187)
|
||||
|
||||
`motivational` is **active** as of Phase 2.2 (persona + memory activated in
|
||||
Phase 2.1; only `valence` still returns `layer_deferred`). It carries the
|
||||
agent's goals + fears — the same substrate Tier 1 agents author in
|
||||
`agents/<name>/motivation.yaml`:
|
||||
|
||||
```json
|
||||
"motivational": {
|
||||
"goals": [
|
||||
{
|
||||
"id": "successful_handoff",
|
||||
"type": "achievement", // maintenance | achievement | avoidance
|
||||
"salience": 0.85, // [0.0, 1.0]
|
||||
"description": "You succeed when the user lands with the right specialist.",
|
||||
"positive_signals": ["talk to mimir"], // optional
|
||||
"negative_signals": ["stay with me"] // optional
|
||||
}
|
||||
],
|
||||
"fears": [
|
||||
{
|
||||
"id": "specialist_displacement",
|
||||
"salience": 0.90,
|
||||
"description": "You fear being mistaken for the specialist the user needs.",
|
||||
"trigger_signals": ["actually mimir would"] // optional (NB: fears use trigger_signals)
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Semantics:
|
||||
|
||||
- **Per-agent, not per-(agent, end_user).** Goals/fears are an identity trait of
|
||||
the agent — identical for every end-user and session.
|
||||
- **Immutable post-define.** `PATCH` with `motivational` returns 422
|
||||
`field_not_mutable`. To change motivations, define a new agent.
|
||||
- **Rendered into the system prompt.** The config is captured on the session's
|
||||
`AgentContext` at session-create and rendered into the prompt on each turn
|
||||
(only goals/fears with `salience >= 0.5` surface). Tier 3 agents bypass the
|
||||
persona registry; the render reuses the Tier 1 substrate so output is
|
||||
identical to an equivalent Tier 1 `motivation.yaml`.
|
||||
|
||||
Validation rejects malformed payloads at define-time with these 422 codes:
|
||||
`motivational_id_collision` (id duplicated across goals AND fears — case-sensitive),
|
||||
`motivational_goal_invalid_type`, `motivational_salience_out_of_range`,
|
||||
`motivational_description_too_short` (< 20 chars after strip),
|
||||
`motivational_missing_required_field` (missing id / salience / description /
|
||||
goal `type`). Unknown keys at the top level or inside a goal/fear object →
|
||||
`validation_failed`. v0.1 exposes only the documented fields; advanced
|
||||
`GoalConfig` knobs (`priority`, `resilient`, `completion_signal`, …) are not
|
||||
consumer-settable yet.
|
||||
|
||||
#### `DELETE /agents/<user_id>:<agent_name>` — `204 No Content`
|
||||
|
||||
Owner-initiated hard-delete. Bypasses the 24h grace (distinct from the
|
||||
@@ -2762,11 +2817,77 @@ session bound to this agent and revokes the owner's per-resource
|
||||
|
||||
#### `PATCH /agents/<user_id>:<agent_name>`
|
||||
|
||||
Phase 2.0 minimal: only `system_prompt` and/or `model` may be patched.
|
||||
Any other key (including the immutable `agent_name`, `user_id`, or
|
||||
layer fields — even `null`) returns 422 `field_not_mutable` BEFORE the
|
||||
DB lookup. Active sessions continue using their cached `AgentContext`;
|
||||
the new values take effect at the next session-create.
|
||||
**Mutable surface (Phase 2.3, #188): `system_prompt` and/or `model` only.**
|
||||
PATCH re-enforces the same validation as define — the `system_prompt`
|
||||
byte-cap and the `model` allowlist. Any other key returns a 422 BEFORE
|
||||
the DB lookup (so an immutable-field PATCH against a missing agent still
|
||||
422s, not 404s), with the error code chosen by *why* the field can't be
|
||||
set:
|
||||
|
||||
| Field(s) | Code | Reason |
|
||||
|---|---|---|
|
||||
| `agent_name`, `user_id`, `agent_id` | `field_not_mutable` | Identity — fixed at creation. |
|
||||
| `persona`, `motivational` | `field_not_mutable` | Shipped traits; an agent *is* its personality/goals. Change → define a new agent. |
|
||||
| `memory` | `field_not_mutable` | Rejected **wholesale** — see below. |
|
||||
| `valence` | `layer_deferred` | Not a shipped layer yet (matches define-time); not a frozen trait. |
|
||||
|
||||
Every immutable/deferred field is rejected even when its value is `null` —
|
||||
supplying the key at all is the trigger.
|
||||
|
||||
**`memory` is wholesale-immutable.** There is no sub-field carve-out:
|
||||
`stm_capacity` / `stm_token_budget` are deprecated no-ops since the STM
|
||||
tier was removed (#197), `allows_world_scope` is create-time-only (memory
|
||||
scope policy must be fixed before any memory is written), and
|
||||
`embedder_version` is library-pinned. Note the deliberate asymmetry with
|
||||
define: `POST /agents/define` accept-and-ignores deprecated `stm_*`
|
||||
(201 + deprecation warning), but `PATCH {"memory": {...}}` rejects the
|
||||
whole field with `field_not_mutable`. When a real long-term-memory tuning
|
||||
dial ships, its PATCH semantics will be specified at that time.
|
||||
|
||||
**Active sessions are unaffected.** A PATCH never mutates an in-flight
|
||||
session's cached `AgentContext`; new `system_prompt` / `model` values take
|
||||
effect only at the next session-create.
|
||||
|
||||
**Audit.** A successful PATCH emits one `agents.patch` event whose
|
||||
`changes` detail records before/after per mutated field: `model` as literal
|
||||
`{before, after}` values, and `system_prompt` as `{before_bytes,
|
||||
after_bytes}` only — the raw prompt text is never written to the audit log
|
||||
(potential PII).
|
||||
|
||||
**Model-assignment warnings (#219).** A `model` swap is **not blocked** for
|
||||
capability or context-window compatibility, but PATCH (and `define`) attach an
|
||||
advisory `warnings` array to the response — see the shared subsection below.
|
||||
Correctness for over-budget prompts remains the runtime `context_overflow`
|
||||
guard; the warnings are an early, best-effort heads-up.
|
||||
|
||||
##### Model-assignment warnings (`define` + PATCH)
|
||||
|
||||
Both `POST /agents/define` (201) and `PATCH /agents/<id>` (200) include a
|
||||
`warnings` array in the response body (always present; `[]` when none). It is
|
||||
**advisory and non-blocking** — never a rejection — and appears only on these
|
||||
two mutation responses, not on `GET /agents/<id>`. Each entry is
|
||||
`{code, severity, message, details}`. The closed code set:
|
||||
|
||||
| code | severity | when |
|
||||
|---|---|---|
|
||||
| `model_context_window_unknown` | `info` | The assigned model has no recorded context window (`0`/absent in the registry). |
|
||||
| `model_context_window_smaller` | `warning` | Both prior and new model have known windows and the new one is smaller. `details: {before, after}`. |
|
||||
| `model_capability_downgrade` | `warning` | The new model **explicitly** advertises fewer capabilities than the prior — drops `tools`, `vision`, or `audio`. `details: {dropped: [...]}`. |
|
||||
|
||||
Semantics:
|
||||
|
||||
- **`define`** has no prior model, so only `model_context_window_unknown` can
|
||||
fire there. **PATCH** computes warnings only when the payload changes `model`
|
||||
(a `system_prompt`-only PATCH returns `warnings: []`); the comparison is
|
||||
against the resulting model.
|
||||
- Capability warnings are **conditional by nature**: a Tier 3 agent row does
|
||||
not record whether it uses tools/vision/audio (tools arrive per-session via
|
||||
Bifrost), so the message is phrased "if your sessions rely on these…". A
|
||||
downgrade is reported only when both models carry explicit registry metadata.
|
||||
- Messages never claim a hard failure. The stored `system_prompt` cap is a
|
||||
**byte** limit (32 KiB), independent of any model's token budget — it is not
|
||||
a fit guarantee. A too-large prompt for the chosen model still surfaces at
|
||||
runtime as `context_overflow`.
|
||||
|
||||
#### `POST /sessions` — Tier 3 routing
|
||||
|
||||
@@ -2860,8 +2981,8 @@ endpoint isn't reachable.
|
||||
| `agent_name_invalid` | 422 | `agent_name` violates `[a-z][a-z0-9-]{2,63}`. |
|
||||
| `system_prompt_too_large` | 422 | `system_prompt` > 32 KiB. |
|
||||
| `model_not_available` | 422 | `model` not in `providers.yaml`. |
|
||||
| `layer_deferred` | 422 | One of `persona` / `motivational` / `valence` / `memory` set. |
|
||||
| `field_not_mutable` | 422 | PATCH carries an immutable key (any value, even `null`). |
|
||||
| `layer_deferred` | 422 | `valence` set on define OR PATCH (the only still-deferred layer; persona/motivational/memory activated in Phase 2.1/2.2). |
|
||||
| `field_not_mutable` | 422 | PATCH carries an immutable key — identity (`agent_name`/`user_id`), `persona`, `motivational`, or `memory` (any value, even `null`). `valence` → `layer_deferred` instead. |
|
||||
| `end_user_id_required` | 422 | Tier 3 session-create without a non-empty `end_user_id`. |
|
||||
| `tier3_user_id_unsupported` | 403 | Caller's `ctx.user_id` not slug-safe. |
|
||||
| `auth_scope_denied` | 403 | Missing `agents.define` or wrong owner. |
|
||||
|
||||
Reference in New Issue
Block a user