feat(agents): bridge AgentStore to Vertz entities (RLS-aware sessions/messages) [#2847]

[viniciusdacal]

Summary

Implements the agent-store ↔ entity bridge designed in #2959 (merged). Agent sessions and messages become first-class Vertz entities, queryable from app code with full rules.* enforcement. Writes still flow through sqliteStore / d1Store / memoryStore — atomic paths unchanged.

Closes #2847.

What ships

New @vertz/agents/entities subpath:

• agentSessionColumns, agentMessageColumns, agentSessionIndexes, agentMessageIndexes — plain constants that developers spread into their own d.table().
• defineAgentEntities(db) factory — looks up the registered tables via db._internals.models, wires entity() definitions with user-scoped defaults, installs a column-aware before.create hook that injects userId / tenantId from the request context (ctx wins — prevents silent impersonation).

Breaking changes (pre-v1, .claude/rules/policies.md):

• AgentStore.appendMessages gains a session: AgentSession parameter — matches appendMessagesAtomic. All three in-repo store impls, run.ts, crash-harness.ts updated.
• agent_messages gains user_id / tenant_id columns (denormalized on every append — required for flat rules.where({ userId })). Fresh installs get them via the stores' updated DDL; existing DBs run the one-shot migration at packages/agents/migrations/001-add-rls-columns.sql.

Adversarial review

Spawned a review agent post-implementation. Three blockers surfaced and all fixed before push:

1. Migration SQL not idempotent — the header comment claimed "safe to run more than once" while the body crashes on a second run. Removed the false claim; documented the need for a migration runner.
2. Docs showed ctx.entities.agentSession.list() — default entity names are kebab (agent-session), ctx.entities does exact-key lookup. Updated docs to use bracket access + documented the lowercase sessionName: 'agentsession' escape hatch for dot-access.
3. before.create hook unconditionally injected tenantId — broke extended schemas that drop the column (the docs themselves recommend this) and could conflict with the CRUD pipeline's multi-level tenancy auto-set. Hook now inspects table._columns and only injects fields the table actually declares.

Two should-fixes also landed:

• Added the missing negative type tests (string-value inside sessionAccess, missing db arg).
• Beefed up the integration test with an extended-schema path (workspaceId custom column, hook-through-entity verification, custom-field query via handlers.list).
• Added a direct store-level assertion that user_id / tenant_id are denormalized onto rows.

Test plan

• vtz run ci:affected — all 254 tests pass, 0 failures. Build + typecheck + lint green.
• vtz run format + format:fix — clean.
• vtz run lint — 0 errors (pre-existing warnings only).
• Integration test in packages/agents/src/entities/__tests__/bridge.integration.test.ts exercises the full path end-to-end: sqliteStore.saveSession + store.appendMessages → entity-side sessionHandlers.list(ctx) → RLS rejects cross-tenant and cross-user-same-tenant reads; extended workspaceId column round-trips through handlers.create + before.create hook.

Design

Merged at #2959 (plans/agent-store-entity-bridge.md). Six review rounds (DX, Product, Technical × 2) settled the architecture, API surface, breaking-change scope, and all API references against real code.

Follow-ups

• chore(agents): reject entity hook registration on factory-produced Session/Message entities #2957 — reject entity hook registration on factory-produced entities (boot-time enforcement of the write-path-bypasses-hooks contract).
• chore(agents): migrate agent_sessions.state and agent_messages.toolCalls to d.jsonb<T>() #2958 — migrate state / toolCalls columns to d.jsonb<T>() with an opt-in flag.

🤖 Generated with Claude Code