@ai-matrx/agents 0.59.270 → 0.59.272

package/CHANGELOG.md

@@ -1,9 +1,24 @@
 # Changelog
 
+## 0.59.272
+
+- New export `./context/rules-corpus.json` (shipped in `files`): the context-rules parity corpus, so a consumer test (chat) reads it through the dependency instead of a path into this package. Additive; no consumer action required.
+
+- `./settings`: `reasoning_effort` leaves `AUTO_MEANS_UNSET_KEYS` — a person's "auto" is saved and
+  sent (owner ruling 2026-10-24: unset effort runs at the platform default "low"; "auto" only when a
+  person picks it). New `NEVER_IMPLICIT_AUTO_KEYS` + `isNeverImplicitChoice`; `startingValueFor`
+  never starts a row at "auto". Consumer action: none beyond adopting latest — every writer reads
+  `isUnsetChoice` already.
+
+## 0.59.271
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 8a4ed656ea 2c48e64133 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.270
 
-UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
-Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/matrx-agents/src`.
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 4c08cba6c4 8a4ed656ea -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
 
 ## 0.59.269
 

package/context/rules-corpus.json

@@ -0,0 +1,238 @@
+{
+  "version": 1,
+  "about": "THE parity corpus for context value rules (common-docs/systems/data/scopes-context/context-delivery/RULES.md). Run by the package vitest (context/rules.test.ts) AND aidream pytest (tests/test_context_rules_corpus.py). Expectations are hand-derived from RULES.md section 2 — never regenerate them from either implementation.",
+  "defaults": { "cap": 50000 },
+  "rules_cases": [
+    { "name": "bare value under default", "input": { "chars": 150 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "bare value at the default is inline (<=)", "input": { "chars": 200 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "bare value one over the default", "input": { "chars": 201 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "unresolved lazy source is on request", "input": { "chars": null }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "server per-key default (small lazy document)", "input": { "default_max": 6000, "chars": 5000 }, "expect": { "include": true, "max_inline_chars": 6000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "server per-key default zero (IDE diagnostics)", "input": { "default_max": 0, "chars": 10 }, "expect": { "include": true, "max_inline_chars": 0, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "page limit raises the default", "input": { "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 7000 }, "expect": { "include": true, "max_inline_chars": 8000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "agent ceiling below page limit wins", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 5000 }, "expect": { "include": true, "max_inline_chars": 1000, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "agent" }, "clamped": false } },
+    { "name": "page limit below agent ceiling wins", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 500 }, "chars": 400 }, "expect": { "include": true, "max_inline_chars": 500, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "agent and page tie — agent named", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 1000 }, "chars": 1000 }, "expect": { "include": true, "max_inline_chars": 1000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "agent" }, "clamped": false } },
+    { "name": "agent declares key without a limit — page limit applies", "input": { "agent": { "declared": true, "max_inline_chars": null }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 3000 }, "expect": { "include": true, "max_inline_chars": 8000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "agent limit ignored when the key is not declared", "input": { "agent": { "declared": false, "max_inline_chars": 1000 }, "chars": 300 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "page zero beats agent ceiling", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 0 }, "chars": 5 }, "expect": { "include": true, "max_inline_chars": 0, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "agent zero with no page", "input": { "agent": { "declared": true, "max_inline_chars": 0 }, "chars": 5 }, "expect": { "include": true, "max_inline_chars": 0, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "agent" }, "clamped": false } },
+    { "name": "page auto_context off drops an undeclared value", "input": { "surface": { "declared": true, "auto_context": false, "max_inline_chars": null }, "chars": 50 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "agent declaration re-admits a page auto_context off value", "input": { "agent": { "declared": true }, "surface": { "declared": true, "auto_context": false }, "chars": 50 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "agent", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "auto_context off on an undeclared surface value is not a page rule", "input": { "surface": { "declared": false, "auto_context": false }, "chars": 50 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "kill switch drops an undeclared key", "input": { "agent": { "declared": false, "kill_switch": true }, "chars": 50 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "agent", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "kill switch keeps a declared key", "input": { "agent": { "declared": true, "kill_switch": true }, "chars": 50 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "kill switch beats a page auto_context on", "input": { "agent": { "declared": false, "kill_switch": true }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 50 }, "expect": { "include": false, "max_inline_chars": 8000, "delivery": "off", "decided_by": { "include": "agent", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "YOU re-admit past the kill switch", "input": { "agent": { "declared": false, "kill_switch": true }, "user": { "include": true }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "YOU re-admit past page auto_context off", "input": { "surface": { "declared": true, "auto_context": false }, "user": { "include": true }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "YOU turn a value off", "input": { "user": { "include": false }, "chars": 100 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "YOU turn off an agent-declared value", "input": { "agent": { "declared": true, "max_inline_chars": 5000 }, "user": { "include": false }, "chars": 100 }, "expect": { "include": false, "max_inline_chars": 5000, "delivery": "off", "decided_by": { "include": "you", "max_inline_chars": "agent" }, "clamped": false } },
+    { "name": "YOUR limit beats a lower agent ceiling", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 500 }, "user": { "max_inline_chars": 20000 }, "chars": 15000 }, "expect": { "include": true, "max_inline_chars": 20000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "YOUR limit zero means never inline", "input": { "user": { "max_inline_chars": 0 }, "chars": 5 }, "expect": { "include": true, "max_inline_chars": 0, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "YOUR limit at exact size is inline", "input": { "user": { "max_inline_chars": 300 }, "chars": 300 }, "expect": { "include": true, "max_inline_chars": 300, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "YOUR limit above the cap is clamped and says so", "input": { "user": { "max_inline_chars": 60000 }, "chars": 55000 }, "expect": { "include": true, "max_inline_chars": 50000, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": true } },
+    { "name": "agent limit above the cap is clamped", "input": { "agent": { "declared": true, "max_inline_chars": 70000 }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 50000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "agent" }, "clamped": true } },
+    { "name": "lowered cap knob clamps a page limit", "input": { "cap": 1000, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 900 }, "expect": { "include": true, "max_inline_chars": 1000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": true } },
+    { "name": "negative user limit is ignored", "input": { "user": { "max_inline_chars": -5 }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "fractional user limit is ignored", "input": { "user": { "max_inline_chars": 12.5 }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "non-boolean user include is ignored", "input": { "user": { "include": "no" }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "user limit only — include still decided by the page", "input": { "surface": { "declared": true, "auto_context": false }, "user": { "max_inline_chars": 900 }, "chars": 100 }, "expect": { "include": false, "max_inline_chars": 900, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "user limit on an unresolved lazy source stays on request", "input": { "user": { "max_inline_chars": 20000 }, "chars": null }, "expect": { "include": true, "max_inline_chars": 20000, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "identity survives the agent kill switch", "input": { "identity": true, "agent": { "declared": false, "kill_switch": true }, "chars": 120 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity survives a page that switched auto context off", "input": { "identity": true, "surface": { "declared": true, "auto_context": false }, "chars": 120 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity under the kill switch: the person's off rule still wins", "input": { "identity": true, "agent": { "declared": false, "kill_switch": true }, "user": { "include": false }, "chars": 120 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "a page's own conversation never gets the page: the lock turns it off", "input": { "surface": { "declared": true, "auto_context": false, "own": true }, "chars": 10 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "the person's saved on rule cannot reopen a page's own conversation", "input": { "surface": { "declared": true, "auto_context": false, "own": true }, "user": { "include": true }, "chars": 10 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "the agent's own declaration cannot reopen a page's own conversation", "input": { "agent": { "declared": true, "kill_switch": false }, "surface": { "declared": true, "auto_context": false, "own": true }, "chars": 10 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity is never locked by a page's own conversation", "input": { "identity": true, "surface": { "declared": true, "auto_context": false, "own": true }, "chars": 10 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity under a switched-off page: the person's off rule still wins", "input": { "identity": true, "surface": { "declared": true, "auto_context": false }, "user": { "include": false }, "chars": 120 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity on the page's own conversation with the person's on rule is sent", "input": { "identity": true, "surface": { "declared": true, "auto_context": false }, "user": { "include": true }, "chars": 120 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "the same page-off layer closes a value that is not identity", "input": { "surface": { "declared": true, "auto_context": false }, "chars": 120 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity's limit still resolves like any value", "input": { "identity": true, "agent": { "declared": false, "kill_switch": true }, "surface": { "declared": true, "auto_context": false, "max_inline_chars": 100 }, "chars": 120 }, "expect": { "include": true, "max_inline_chars": 100, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "a value that is not identity is still closed by the kill switch", "input": { "identity": false, "agent": { "declared": false, "kill_switch": true }, "chars": 120 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "agent", "max_inline_chars": "default" }, "clamped": false } }
+  ],
+  "lookup_cases": [
+    { "name": "no rows", "rows": {}, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": null },
+    { "name": "default row only", "rows": { "_default": { "note_bundle": { "include": false } } }, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": { "include": false } },
+    { "name": "surface row merges over default per field", "rows": { "_default": { "note_bundle": { "max_inline_chars": 1000 } }, "matrx-user/notes": { "note_bundle": { "include": false } } }, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": { "include": false, "max_inline_chars": 1000 } },
+    { "name": "surface row field wins over default field", "rows": { "_default": { "note_bundle": { "include": false } }, "matrx-user/notes": { "note_bundle": { "include": true } } }, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": { "include": true } },
+    { "name": "other surface rows never apply", "rows": { "matrx-user/tasks": { "note_bundle": { "include": false } } }, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": null },
+    { "name": "no-surface value reads the default row", "rows": { "_default": { "attached_document_1": { "max_inline_chars": 9000 } } }, "surface_key": "_default", "key": "attached_document_1", "expect": { "max_inline_chars": 9000 } },
+    { "name": "other key absent", "rows": { "_default": { "a": { "include": false } } }, "surface_key": "_default", "key": "b", "expect": null }
+  ],
+  "chars_cases": [
+    { "name": "plain string", "value": "hello", "chars": 5 },
+    { "name": "empty string", "value": "", "chars": 0 },
+    { "name": "accented string counts code points", "value": "héllo", "chars": 5 },
+    { "name": "astral emoji is ONE code point (JS .length would say 2)", "value": "😀ab", "chars": 3 },
+    { "name": "string with a raw newline is itself", "value": "a\nb", "chars": 3 },
+    { "name": "object pretty-printed at indent 2", "value": { "a": 1 }, "chars": 12 },
+    { "name": "empty object", "value": {}, "chars": 2 },
+    { "name": "empty array", "value": [], "chars": 2 },
+    { "name": "array pretty-printed", "value": [1, 2], "chars": 12 },
+    { "name": "nested with empty array", "value": { "a": { "b": [] } }, "chars": 28 },
+    { "name": "object with non-ASCII value (ensure_ascii off)", "value": { "k": "é😀" }, "chars": 15 },
+    { "name": "object with newline in a string escapes it", "value": { "t": "a\nb" }, "chars": 17 },
+    { "name": "boolean", "value": true, "chars": 4 },
+    { "name": "null", "value": null, "chars": 4 },
+    { "name": "integer", "value": 42, "chars": 2 }
+  ],
+  "server_default_cases": [
+    { "name": "plain string has no server default", "value": "hello", "expect": null },
+    { "name": "plain object has no server default", "value": {"a": 1}, "expect": null },
+    { "name": "envelope with content only", "value": {"content": "x", "label": "Note"}, "expect": null },
+    { "name": "envelope default_max_inline_chars is the server default", "value": {"content": "x", "default_max_inline_chars": 9000}, "expect": 9000 },
+    { "name": "envelope default zero (IDE diagnostics)", "value": {"content": "x", "default_max_inline_chars": 0}, "expect": 0 },
+    { "name": "negative envelope default is ignored", "value": {"content": "x", "default_max_inline_chars": -1}, "expect": null },
+    { "name": "boolean envelope default is ignored", "value": {"content": "x", "default_max_inline_chars": true}, "expect": null },
+    { "name": "fractional envelope default is ignored", "value": {"content": "x", "default_max_inline_chars": 12.5}, "expect": null },
+    { "name": "string envelope default is ignored", "value": {"content": "x", "default_max_inline_chars": "9000"}, "expect": null },
+    { "name": "a page limit is not a server default", "value": {"content": "x", "max_inline_chars": 8000}, "expect": null },
+    { "name": "lazy source pointer (no content) is 6000", "value": {"source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111", "field": "content"}, "type": "json", "label": "Doc"}, "expect": 6000 },
+    { "name": "lazy source with null content is 6000", "value": {"content": null, "source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}}, "expect": 6000 },
+    { "name": "a source with content is not lazy", "value": {"content": "body", "source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}}, "expect": null },
+    { "name": "normalized resource source is descriptor-first", "value": {"source": {"kind": "file", "id": "11111111-1111-4111-8111-111111111111", "extra": {"resource_type": "file"}}, "type": "json"}, "expect": 0 },
+    { "name": "explicit default beats the lazy default", "value": {"source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}, "default_max_inline_chars": 100}, "expect": 100 },
+    { "name": "a source without kind is raw content", "value": {"source": {"id": "11111111-1111-4111-8111-111111111111"}}, "expect": null },
+    { "name": "an unknown key makes the dict raw JSON", "value": {"content": "x", "default_max_inline_chars": 9000, "other": 1}, "expect": null },
+    { "name": "bare resource reference is descriptor-first", "value": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "11111111-1111-4111-8111-111111111111"}, "expect": 0 },
+    { "name": "resource reference nested as envelope content is not promoted", "value": {"content": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "11111111-1111-4111-8111-111111111111"}}, "expect": null },
+    { "name": "resource reference without a UUID id is raw content", "value": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "not-a-uuid"}, "expect": null }
+  ],
+  "envelope_cases": [
+    { "name": "a record that merely has content is raw content", "value": {"id": "11111111-1111-4111-8111-111111111111", "title": "Q3 vendor review", "content": "Follow up with Acme"}, "expect": {"content": {"id": "11111111-1111-4111-8111-111111111111", "title": "Q3 vendor review", "content": "Follow up with Acme"}, "overrides": {}} },
+    { "name": "a true envelope splits content from its fields", "value": {"content": "Follow up with Acme", "label": "Current note", "max_inline_chars": 8000}, "expect": {"content": "Follow up with Acme", "overrides": {"label": "Current note", "max_inline_chars": 8000}} },
+    { "name": "an envelope with an unknown key is raw content", "value": {"content": "x", "label": "L", "pinned": true}, "expect": {"content": {"content": "x", "label": "L", "pinned": true}, "overrides": {}} },
+    { "name": "an envelope keeps default_max_inline_chars as a field", "value": {"content": "2 errors", "default_max_inline_chars": 0}, "expect": {"content": "2 errors", "overrides": {"default_max_inline_chars": 0}} },
+    { "name": "a lazy source pointer has null content", "value": {"source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}, "type": "json", "label": "Doc"}, "expect": {"content": null, "overrides": {"source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}, "type": "json", "label": "Doc"}} },
+    { "name": "a source without kind and no content is raw content", "value": {"source": {"id": "11111111-1111-4111-8111-111111111111"}, "label": "Doc"}, "expect": {"content": {"source": {"id": "11111111-1111-4111-8111-111111111111"}, "label": "Doc"}, "overrides": {}} },
+    { "name": "a plain string is content", "value": "hello", "expect": {"content": "hello", "overrides": {}} },
+    { "name": "an array is content", "value": [1, 2], "expect": {"content": [1, 2], "overrides": {}} }
+  ],
+  "wire_passthrough_cases": [
+    { "name": "an attached file reference ships as-is", "key": "attached_file_22222222-2222-4222-8222-222222222222", "value": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "22222222-2222-4222-8222-222222222222"}, "passthrough": true },
+    { "name": "a reference with its own policy ships as-is", "key": "attached_file_22222222-2222-4222-8222-222222222222", "value": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "22222222-2222-4222-8222-222222222222", "promote": [{"representation": "clean_text", "max_chars": 5000}], "exclude": ["image"]}, "passthrough": true },
+    { "name": "a processed document reference ships as-is", "key": "source_doc", "value": {"__kind": "resource_ref", "resource_type": "processed_document", "resource_id": "22222222-2222-4222-8222-222222222222"}, "passthrough": true },
+    { "name": "a bare file id under file_id ships as-is", "key": "file_id", "value": "22222222-2222-4222-8222-222222222222", "passthrough": true },
+    { "name": "a bare file id under a *_file_id key ships as-is", "key": "attached_file_id", "value": "22222222-2222-4222-8222-222222222222", "passthrough": true },
+    { "name": "a record with content is wrapped", "key": "current_note", "value": {"id": "22222222-2222-4222-8222-222222222222", "title": "Q3 vendor review", "content": "Follow up"}, "passthrough": false },
+    { "name": "a plain string is wrapped", "key": "current_note", "value": "Follow up with Acme", "passthrough": false }
+  ],
+  "server_resolved_cases": [
+    { "name": "bare note id is server-resolved", "key": "note_id", "value": "33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": true },
+    { "name": "prefixed note id is server-resolved", "key": "current_note_id", "value": "33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": true },
+    { "name": "an id key is case-insensitive", "key": "Note_ID", "value": "33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": true },
+    { "name": "a braced UUID is a UUID", "key": "file_id", "value": "{33333333-3333-4333-8333-333333333333}", "expect": true, "server_promotes": true },
+    { "name": "a hyphenless UUID is a UUID", "key": "file_id", "value": "33333333333343338333333333333333", "expect": true, "server_promotes": true },
+    { "name": "a urn UUID is a UUID", "key": "note_id", "value": "urn:uuid:33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": true },
+    { "name": "a top-level resource reference is server-resolved", "key": "current_note", "value": {"__kind": "resource_ref", "resource_type": "note", "resource_id": "33333333-3333-4333-8333-333333333333"}, "expect": true, "server_promotes": true },
+    { "name": "an unregistered id noun: the client stops predicting, the server keeps it raw", "key": "model_id", "value": "33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": false },
+    { "name": "a resource reference as envelope content: the client stops predicting", "key": "current_note", "value": {"content": {"__kind": "resource_ref", "resource_type": "note", "resource_id": "33333333-3333-4333-8333-333333333333"}, "label": "Note"}, "expect": true, "server_promotes": false },
+    { "name": "a UUID under a non-id key is plain text", "key": "note", "value": "33333333-3333-4333-8333-333333333333", "expect": false, "server_promotes": false },
+    { "name": "a non-UUID under an id key is plain text", "key": "note_id", "value": "not-a-uuid", "expect": false, "server_promotes": false },
+    { "name": "a plain record is not server-resolved", "key": "current_note", "value": {"id": "33333333-3333-4333-8333-333333333333", "title": "Q3 vendor review", "content": "Follow up"}, "expect": false, "server_promotes": false }
+  ],
+  "effective_lookup_cases": [
+    { "name": "declared on both sides: page key", "rows": {"matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/notes", "key": "current_note_published_to_web", "expect": {"include": false} },
+    { "name": "declared client-only: the server files it under _default and still reads the page rule", "rows": {"matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": {"include": false} },
+    { "name": "rule in _default only, page key", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/notes", "key": "current_note_published_to_web", "expect": {"max_inline_chars": 1000} },
+    { "name": "rule in _default only, _default key", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": {"max_inline_chars": 1000} },
+    { "name": "rule in P only, _default key", "rows": {"matrx-user/notes": {"attached_document_1": {"max_inline_chars": 9000}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "attached_document_1", "expect": {"max_inline_chars": 9000} },
+    { "name": "both rows merge per field, page key", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}, "matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/notes", "key": "current_note_published_to_web", "expect": {"include": false, "max_inline_chars": 1000} },
+    { "name": "both rows merge per field, _default key", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}, "matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": {"include": false, "max_inline_chars": 1000} },
+    { "name": "P wins a field both rows set", "rows": {"_default": {"current_note_published_to_web": {"include": true, "max_inline_chars": 1000}}, "matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": {"include": false, "max_inline_chars": 1000} },
+    { "name": "a surroundings key keeps its own surface", "rows": {"matrx-user/sidebar": {"sidebar_filter": {"include": false}}, "matrx-user/notes": {"sidebar_filter": {"include": true}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/sidebar", "key": "sidebar_filter", "expect": {"include": false} },
+    { "name": "a surroundings key never reads P", "rows": {"matrx-user/notes": {"sidebar_filter": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/sidebar", "key": "sidebar_filter", "expect": null },
+    { "name": "no primary surface: _default key reads _default only", "rows": {"matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": null, "surface_key": "_default", "key": "current_note_published_to_web", "expect": null },
+    { "name": "no primary surface: surface key merges as before", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}, "matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": null, "surface_key": "matrx-user/notes", "key": "current_note_published_to_web", "expect": {"include": false, "max_inline_chars": 1000} },
+    { "name": "other surfaces' rows never apply", "rows": {"matrx-user/tasks": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": null },
+    { "name": "a value a screen mounted inside the page published keeps that screen's surface", "rows": {"matrx-user/transcripts": {"transcript_title": {"include": false}}, "matrx-user/knowledge": {"transcript_title": {"include": true, "max_inline_chars": 9}}, "_default": {"transcript_title": {"max_inline_chars": 700}}}, "primary_surface": "matrx-user/knowledge", "surface_key": "matrx-user/transcripts", "origin": "client", "key": "transcript_title", "expect": {"include": false, "max_inline_chars": 700} },
+    { "name": "a mounted screen's value never reads the primary's row", "rows": {"matrx-user/knowledge": {"transcript_title": {"include": false}}}, "primary_surface": "matrx-user/knowledge", "surface_key": "matrx-user/transcripts", "origin": "client", "key": "transcript_title", "expect": null }
+  ],
+  "humanize_cases": [
+    { "name": "snake case to title words", "key": "current_note", "expect": "Current Note" },
+    { "name": "id is an acronym", "key": "note_id", "expect": "Note ID" },
+    { "name": "a long page key", "key": "current_note_published_to_web", "expect": "Current Note Published To Web" },
+    { "name": "several acronyms", "key": "source_url_pdf", "expect": "Source URL PDF" },
+    { "name": "acronyms are whole parts only", "key": "url2pdf_source", "expect": "Url2pdf Source" },
+    { "name": "hyphens split like underscores", "key": "ai-model-settings", "expect": "AI Model Settings" },
+    { "name": "runs of separators collapse", "key": "attached__file--id", "expect": "Attached File ID" },
+    { "name": "leading and trailing separators drop", "key": "_internal_key_", "expect": "Internal Key" },
+    { "name": "upper-case input is normalized", "key": "API_KEY_STATUS", "expect": "API Key Status" },
+    { "name": "camelCase splits into words", "key": "myValue_ID", "expect": "My Value ID" },
+    { "name": "uuid and json", "key": "resource_uuid_json", "expect": "Resource UUID JSON" },
+    { "name": "every listed acronym", "key": "id_url_pdf_html_json_api_ai_ui_csv_sms_seo_llm_mcp_uuid_iso", "expect": "ID URL PDF HTML JSON API AI UI CSV SMS SEO LLM MCP UUID ISO" },
+    { "name": "a word that only contains an acronym stays a word", "key": "idea_guide", "expect": "Idea Guide" },
+    { "name": "digits stay", "key": "attached_document_2", "expect": "Attached Document 2" },
+    { "name": "a single word", "key": "notes", "expect": "Notes" },
+    { "name": "empty key", "key": "", "expect": "" },
+    { "name": "already words stay as written", "key": "Normal Text", "expect": "Normal Text" },
+    { "name": "a person's phrase keeps its casing and apostrophe", "key": "Customer's iPhone model", "expect": "Customer's iPhone model" },
+    { "name": "a phrase with a version number is not split on the dot", "key": "Version 2.0", "expect": "Version 2.0" },
+    { "name": "a lowercase phrase gains only a capital first letter", "key": "lowercase words here", "expect": "Lowercase words here" },
+    { "name": "a plural acronym tail stays whole", "key": "userIDs", "expect": "User IDs" },
+    { "name": "a plural acronym part", "key": "user_ids", "expect": "User IDs" },
+    { "name": "api key", "key": "api_key", "expect": "API Key" },
+    { "name": "user id", "key": "user_id", "expect": "User ID" },
+    { "name": "an upper-case run before a word splits", "key": "HTMLParser", "expect": "HTML Parser" },
+    { "name": "digits stay inside a part", "key": "step2_output", "expect": "Step2 Output" },
+    { "name": "a short versioned key", "key": "v2", "expect": "V2" },
+    { "name": "no key at all", "key": null, "expect": "" }
+  ],
+  "attachment_key_cases_about": "attached_resource_ + encode(provider + ':' + resource_ref): ASCII letters, digits and '-' kept; every other UTF-8 byte is '_' + two lowercase hex digits ('_' itself is _5f), so the key is unique across providers, case-preserving and stable, and every client derives it from GET /conversations/{id}/attachments (provider, resource_ref).",
+  "attachment_key_cases": [
+    { "name": "a GitHub repository", "provider": "github", "resource_ref": "harbor-point/work-orders", "expect": "attached_resource_github_3aharbor-point_2fwork-orders" },
+    { "name": "a Drive file id keeps its case", "provider": "google", "resource_ref": "1AbCvendorSchedule", "expect": "attached_resource_google_3a1AbCvendorSchedule" },
+    { "name": "ids that differ only by case stay distinct", "provider": "google", "resource_ref": "1abcvendorschedule", "expect": "attached_resource_google_3a1abcvendorschedule" },
+    { "name": "an underscore is escaped, so it never collides with a slash", "provider": "github", "resource_ref": "harbor_point/ops", "expect": "attached_resource_github_3aharbor_5fpoint_2fops" },
+    { "name": "slash form", "provider": "github", "resource_ref": "a/b", "expect": "attached_resource_github_3aa_2fb" },
+    { "name": "underscore form", "provider": "github", "resource_ref": "a_b", "expect": "attached_resource_github_3aa_5fb" },
+    { "name": "the same ref under another provider is another key", "provider": "microsoft", "resource_ref": "1AbC", "expect": "attached_resource_microsoft_3a1AbC" },
+    { "name": "the same ref under Google", "provider": "google", "resource_ref": "1AbC", "expect": "attached_resource_google_3a1AbC" },
+    { "name": "a synced record ref with dots, colons and @", "provider": "google", "resource_ref": "calendar.events:abc123@google.com", "expect": "attached_resource_google_3acalendar_2eevents_3aabc123_40google_2ecom" },
+    { "name": "non-ASCII is escaped byte by byte (UTF-8)", "provider": "github", "resource_ref": "café", "expect": "attached_resource_github_3acaf_c3_a9" },
+    { "name": "spaces and dots", "provider": "microsoft", "resource_ref": "Q4 Budget.xlsx", "expect": "attached_resource_microsoft_3aQ4_20Budget_2exlsx" },
+    { "name": "an empty ref still names the provider", "provider": "github", "resource_ref": "", "expect": "attached_resource_github_3a" }
+  ],
+  "server_authoritative_keys_about": "The keys whose value the SERVER states itself, never the client's copy (RULES.md section 5a, owner ruling 2026-10-01: identity is the server's truth, never the page's claim), and where it states each: active_context = the turn's <active_context> block; manifest = a server-built context value. aidream SERVER_AUTHORITATIVE_KEYS and the package SERVER_AUTHORITATIVE_KEYS must equal this table exactly.",
+  "server_authoritative_keys": { "user": "manifest", "client": "manifest", "organization": "active_context", "active_scopes": "active_context" },
+  "pointer_inline_ceilings_about": "The page-layer limits the client DERIVES instead of reading from the page (owner ruling 2026-09-30, the person's pointer): a selection and the text around it inline up to these sizes on every page, never below the page's own number; pageless_content is a launch with no page behind it. A sent value carries the number on its envelope; a WITHHELD value does not, so the server holds the same table for its receipt row. matrx-frontend POINTER_INLINE_CEILINGS / PAGELESS_CONTENT_INLINE_CEILING and aidream POINTER_INLINE_CEILINGS / PAGELESS_CONTENT_INLINE_CEILING must equal this table exactly.",
+  "pointer_inline_ceilings": { "selection": 10000, "text_before": 2500, "text_after": 2500 },
+  "pageless_content_inline_ceiling": 6000,
+  "consumed_key_cases_about": "The reserved keys the server never keeps under their own name (RULES.md section 5 consumed_as): each still gets a receipt row naming what became of it. aidream RESERVED_CONSUMED_KEYS and the package RESERVED_CONSUMED_KEYS must equal this table exactly.",
+  "consumed_key_cases": [
+    { "name": "the registered screens around the page expand into <surface>::<value> rows", "key": "surface_chain", "consumed_as": "expanded" },
+    { "name": "open unregistered windows expand into window::<title> rows", "key": "window_forms", "consumed_as": "expanded" },
+    { "name": "a table-access grant is a directive the server acts on", "key": "__table_access", "consumed_as": "directive" },
+    { "name": "attached Google files are a directive the server acts on", "key": "__google_files", "consumed_as": "directive" },
+    { "name": "an Orchestra member step's connection is a directive the server acts on", "key": "__orchestra_member", "consumed_as": "directive" }
+  ],
+  "surroundings_key_cases_about": "The key the server delivers each value of a surface_chain level under (aidream chain_context_key), which the composer lists before the send (expandSurroundingsForDisplay): one key, so the composer, the person's rule and the receipt name the same value.",
+  "surroundings_key_cases": [
+    { "name": "the canvas beside the chat delivers its active organization id under its own surface", "surface": "matrx-user/canvas", "value": "active_organization_id", "key": "matrx-user/canvas::active_organization_id" },
+    { "name": "a window's value keeps its window surface", "surface": "matrx-user/data-tables-row-editor", "value": "row_draft", "key": "matrx-user/data-tables-row-editor::row_draft" }
+  ],
+  "page_context_cases_about": "RULES.md section 0: a page's OWN conversation (mode own) and a conversation whose page switch is off (mode off) never receive the page. The listed keys are withheld at the PAGE layer (declared, auto_context off), as is any value from the screens around the page (origin surroundings) and any value the page itself declared; the person values are never withheld. withheld null = the default list for the mode. aidream page_context.py and the package's pageContextWithholds must agree with every case.",
+  "page_context_defaults": {
+    "off": ["route_brief", "surface_chain", "window_forms", "surface_closed"],
+    "own": ["route_brief", "surface_chain", "window_forms", "surface_closed", "conversation"],
+    "person_values": ["user", "client", "organization", "project", "task", "active_scopes"]
+  },
+  "page_context_cases": [
+    { "name": "an own conversation never gets its route", "mode": "own", "withheld": null, "key": "route_brief", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": true },
+    { "name": "an own conversation never gets its own id", "mode": "own", "withheld": null, "key": "conversation", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": true },
+    { "name": "a switched-off page still lets the conversation know its id", "mode": "off", "withheld": null, "key": "conversation", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "a switched-off page withholds its route", "mode": "off", "withheld": null, "key": "route_brief", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": true },
+    { "name": "the person is never withheld", "mode": "own", "withheld": null, "key": "user", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "the organization is never withheld, even when the page declares it", "mode": "own", "withheld": null, "key": "organization", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/chat", "expect": false },
+    { "name": "the conversation's working document is never withheld, even when the page declares the name", "mode": "own", "withheld": null, "key": "working_document", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/chat", "expect": false },
+    { "name": "the conversation's scratchpad is never withheld from its own conversation", "mode": "own", "withheld": null, "key": "user_scratchpad", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/chat", "expect": false },
+    { "name": "an attached scratchpad is never withheld by a switched-off page", "mode": "off", "withheld": null, "key": "user_scratchpad_ab12cd34", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/chat", "expect": false },
+    { "name": "a page's own declared value is withheld from its own conversation", "mode": "own", "withheld": null, "key": "battle_columns", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/agent-battle", "expect": true },
+    { "name": "a screen around the page is withheld", "mode": "own", "withheld": null, "key": "matrx-user/notes::content", "origin": "surroundings", "surface_declared": true, "surface_key": "matrx-user/notes", "expect": true },
+    { "name": "an attachment is not the page", "mode": "own", "withheld": null, "key": "attached_document_x", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "a page that declares its own list overrides the default", "mode": "own", "withheld": ["conversation"], "key": "route_brief", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "a declared list can never withhold the person", "mode": "own", "withheld": ["user", "conversation"], "key": "user", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "a switched-off page withholds what a screen mounted inside it published", "mode": "off", "withheld": null, "key": "transcript_title", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/transcripts", "expect": true }
+  ]
+}

package/dist/models/index.cjs

@@ -38,6 +38,7 @@ __export(models_exports, {
   GgufError: () => GgufError,
   INPUT_MODALITIES: () => INPUT_MODALITIES,
   INTERACTION_MODES: () => INTERACTION_MODES,
+  LLM_INTERACTIONS: () => LLM_INTERACTIONS,
   MAX_SUCCESSION_HOPS: () => MAX_SUCCESSION_HOPS,
   MODEL_CATALOG_KINDS: () => MODEL_CATALOG_KINDS,
   MODEL_FAVORITE_ENTITY_TYPE: () => MODEL_FAVORITE_ENTITY_TYPE,
@@ -47,6 +48,7 @@ __export(models_exports, {
   SERVICE_LABEL_PLURAL: () => SERVICE_LABEL_PLURAL,
   TOP_TIER_COST_RATING: () => TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE: () => TOP_TIER_LOCKED_TITLE,
+  UNKNOWN_MODEL_KIND: () => UNKNOWN_MODEL_KIND,
   acceptsTextInstructions: () => acceptsTextInstructions,
   announceModelCatalogChanged: () => announceModelCatalogChanged,
   availableOnDevices: () => availableOnDevices,
@@ -57,6 +59,7 @@ __export(models_exports, {
   catalogForApp: () => catalogForApp,
   catalogKeyColumn: () => catalogKeyColumn,
   catalogKindOf: () => catalogKindOf,
+  catalogKindVerdict: () => catalogKindVerdict,
   cheapestAdequateModel: () => cheapestAdequateModel,
   classConfigKey: () => classConfigKey,
   collapseTiersByClass: () => collapseTiersByClass,
@@ -74,6 +77,7 @@ __export(models_exports, {
   fitsNeed: () => fitsNeed,
   fitsThisComputer: () => fitsThisComputer,
   followModelCatalogChanges: () => followModelCatalogChanges,
+  followModelCatalogVisibility: () => followModelCatalogVisibility,
   formatMemoryBytes: () => formatMemoryBytes,
   fromDiscovery: () => fromDiscovery,
   ggufEngine: () => ggufEngine,
@@ -122,6 +126,7 @@ __export(models_exports, {
   readDeviceModelFiles: () => readDeviceModelFiles,
   readGgufHeader: () => readGgufHeader,
   readModelCatalog: () => readModelCatalog,
+  readModelCatalogStamp: () => readModelCatalogStamp,
   readModelIdentities: () => readModelIdentities,
   readPublicModel: () => readPublicModel,
   reconcileModelFavoriteIds: () => reconcileModelFavoriteIds,
@@ -937,42 +942,6 @@ var OUTPUT_MODALITIES = [
   "decision"
 ];
 
-// models/catalog/changes.ts
-var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
-function hub() {
-  const g = globalThis;
-  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
-}
-function isModelCatalogChange(payload) {
-  const catalog = payload?.["catalog"];
-  return catalog === void 0 || catalog === null || catalog === "models";
-}
-function onModelCatalogChanged(listener) {
-  const h = hub();
-  h.listeners.add(listener);
-  return () => {
-    h.listeners.delete(listener);
-  };
-}
-function modelCatalogRevision() {
-  return hub().revision;
-}
-function announceModelCatalogChanged(payload = {}) {
-  if (!isModelCatalogChange(payload)) return;
-  const h = hub();
-  h.revision += 1;
-  for (const l of [...h.listeners]) {
-    try {
-      l(payload);
-    } catch (err) {
-      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
-    }
-  }
-}
-function followModelCatalogChanges(subscribe) {
-  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
-}
-
 // models/label.ts
 function modelDisplayLabel(row) {
   if (!row) return void 0;
@@ -1564,6 +1533,102 @@ async function readPublicModel(client, key) {
   if (error) return { row: null, error: error.message };
   return { row: data ?? null, error: null };
 }
+async function readModelCatalogStamp(client) {
+  const q = client.schema("ai").from("model_definition").select("updated_at").order("updated_at", { ascending: false, nullsFirst: false });
+  if (!q.limit) throw new Error("readModelCatalogStamp: the client has no .limit() (a supabase-js client does)");
+  const { data, error } = await q.limit(1).maybeSingle();
+  if (error) throw new Error(error.message);
+  const stamp = data?.updated_at;
+  return typeof stamp === "string" ? stamp : null;
+}
+
+// models/catalog/changes.ts
+var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function isModelCatalogChange(payload) {
+  const catalog = payload?.["catalog"];
+  return catalog === void 0 || catalog === null || catalog === "models";
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+function announceModelCatalogChanged(payload = {}) {
+  if (!isModelCatalogChange(payload)) return;
+  const h = hub();
+  h.revision += 1;
+  for (const l of [...h.listeners]) {
+    try {
+      l(payload);
+    } catch (err) {
+      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
+    }
+  }
+}
+function followModelCatalogChanges(subscribe) {
+  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+}
+function followModelCatalogVisibility(options) {
+  const page = options.page ?? (typeof document !== "undefined" && typeof window !== "undefined" ? { document, window } : null);
+  if (!page) return () => {
+  };
+  const minIntervalMs = options.minIntervalMs ?? 2e4;
+  const now = options.now ?? (() => Date.now());
+  const sink = options.errorSink ?? ((e) => {
+    console.error(`[@ai-matrx/agents/models] ${e.code}: ${e.message}`);
+  });
+  let baseline;
+  let inFlight = null;
+  let lastShownRead = -Infinity;
+  const stamp = () => inFlight ??= readModelCatalogStamp(options.client).finally(() => {
+    inFlight = null;
+  });
+  const fail = (err) => sink({ code: "model-catalog-stamp-failed", message: err instanceof Error ? err.message : String(err) });
+  const learnBaseline = () => {
+    if (baseline !== void 0) return;
+    void stamp().then((s4) => {
+      if (baseline === void 0) baseline = s4;
+    }, fail);
+  };
+  const onHidden = () => {
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  };
+  const onShown = () => {
+    if (page.document.visibilityState === "hidden") return;
+    const t = now();
+    if (t - lastShownRead < minIntervalMs) return;
+    lastShownRead = t;
+    const known = baseline;
+    if (known === void 0) return learnBaseline();
+    void stamp().then((s4) => {
+      if (s4 === known) return;
+      baseline = s4;
+      announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
+    }, fail);
+  };
+  const offChanges = onModelCatalogChanged(() => {
+    baseline = void 0;
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  });
+  const onVisibility = () => page.document.visibilityState === "hidden" ? onHidden() : onShown();
+  page.document.addEventListener("visibilitychange", onVisibility);
+  page.window.addEventListener("focus", onShown);
+  if (page.document.visibilityState === "hidden") learnBaseline();
+  return () => {
+    offChanges();
+    page.document.removeEventListener("visibilitychange", onVisibility);
+    page.window.removeEventListener("focus", onShown);
+  };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };
@@ -2819,6 +2884,7 @@ var DeviceModelUnavailableError = class extends Error {
 };
 
 // models/catalog-reader.ts
+var UNKNOWN_MODEL_KIND = "unknown";
 var MODEL_CATALOG_KINDS = /* @__PURE__ */ new Set([
   "llm_model",
   "whisper_model",
@@ -2827,23 +2893,35 @@ var MODEL_CATALOG_KINDS = /* @__PURE__ */ new Set([
   "video_gen_model",
   "ner_model",
   "wake_word_model",
-  "lora"
+  "lora",
+  "embedding_model",
+  UNKNOWN_MODEL_KIND
 ]);
-function catalogKindOf(m, kindOfEntry) {
+var LLM_INTERACTIONS = /* @__PURE__ */ new Set(["turn", "single", "agent"]);
+function catalogKindVerdict(m, kindOfEntry) {
   for (const v of m.variants)
     for (const id of v.catalog_entry_ids ?? []) {
       const k = kindOfEntry.get(id);
-      if (k && MODEL_CATALOG_KINDS.has(k)) return k;
+      if (k && k !== UNKNOWN_MODEL_KIND && MODEL_CATALOG_KINDS.has(k)) return { kind: k, reason: null };
     }
   const out = m.capabilities.output ?? [];
   const inp = m.capabilities.input ?? [];
-  if (m.presentation?.shelf === "loras") return "lora";
-  if (out.includes("video")) return "video_gen_model";
-  if (out.includes("image")) return "image_gen_model";
-  if (out.includes("audio")) return "tts_model_file";
-  if (inp.includes("audio")) return "whisper_model";
-  if (m.capabilities.interaction === "extraction") return "ner_model";
-  return "llm_model";
+  const interaction = m.capabilities.interaction ?? "";
+  const placed = (kind) => ({ kind, reason: null });
+  if (m.presentation?.shelf === "loras" || interaction === "adapter") return placed("lora");
+  if (out.includes("video")) return placed("video_gen_model");
+  if (out.includes("image")) return placed("image_gen_model");
+  if (out.includes("embedding")) return placed("embedding_model");
+  if (out.includes("audio")) return placed("tts_model_file");
+  if (inp.includes("audio") && (out.includes("decision") || interaction === "detection")) return placed("wake_word_model");
+  if (inp.includes("audio") && out.includes("text")) return placed("whisper_model");
+  if (interaction === "extraction") return placed("ner_model");
+  if (inp.includes("text") && out.includes("text") && LLM_INTERACTIONS.has(interaction)) return placed("llm_model");
+  const shape = `input [${inp.join(", ")}], output [${out.join(", ")}], interaction ${interaction || "(none)"}`;
+  return { kind: UNKNOWN_MODEL_KIND, reason: `no kind rule places ${shape}` };
+}
+function catalogKindOf(m, kindOfEntry) {
+  return catalogKindVerdict(m, kindOfEntry).kind;
 }
 function canonicalJson(value) {
   if (value === void 0) return "null";
@@ -2922,6 +3000,8 @@ async function readCatalogWith(client, opts, preread) {
     const p = presentationOf.get(c.id);
     stamp(p);
     const maker = providerById.get(s3(m.provider_id));
+    const verdict = catalogKindVerdict(c, kindOfEntry);
+    if (verdict.reason) warnings.push(`${s3(m.name)}: kind unknown: ${verdict.reason}`);
     return [
       {
         id: s3(m.id),
@@ -2932,7 +3012,7 @@ async function readCatalogWith(client, opts, preread) {
         maker_logo_file_id: sn3(maker?.logo_file_id),
         description: sn3(m.description),
         capabilities: m.capabilities ?? {},
-        kind: catalogKindOf(c, kindOfEntry),
+        kind: verdict.kind,
         offered: c.offered,
         updated_at: c.updated_at,
         presentation: p ? {