docs(agent-workflows): note the session_streams tags/flags schema drift

[mmabrouk]

What

A design note recording a schema drift the big-agents pull left behind: the UI streaming path 500s (sign HTTP 500) while batch invoke is unaffected.

Root cause

Commit 22d843c0ae edited migration oss000000008_add_session_streams.py in place after it had already been applied. It renamed the status JSONB column to tags and added meta. Alembic keys off the revision id, so existing databases never re-run it and keep the old columns.

Meanwhile the code reads the new columns:

• api/oss/src/dbs/postgres/sessions/streams/dbes.py:21-28 mixes in FlagsDBA, TagsDBA, MetaDBA.
• api/oss/src/dbs/postgres/sessions/streams/dao.py:58,76 runs select(SessionStreamDBE), which expands to a SELECT naming tags/meta.
• api/oss/src/dbs/postgres/sessions/streams/mappings.py:24,48,62-63 read/write stream_dbe.tags.

On a stale DB: column session_streams.tags does not exist -> 500.

Recommended fix

A new idempotent forward migration (oss000000009) that ADD COLUMN IF NOT EXISTS tags JSONB / meta JSON. No-op on fresh DBs, fix on stale ones. Aligning the code instead would drop first-class DTO fields, so not recommended.

Full note: docs/design/agent-workflows/projects/builder-agent-reliability/streaming-schema-drift/README.md.

https://claude.ai/code/session_01WSp2LqKrEtXnm2fsPWuQWa

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 1, 2026 10:41pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e3baa3c5-1972-4be2-afcf-b26a4c5a77b1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/session-streams-schema-drift

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

Review request: docs-only. Confirm the recommended fix is right: a new idempotent forward migration (oss000000009) that ADD COLUMN IF NOT EXISTS tags/meta, rather than aligning the code (which would drop first-class SessionStream.tags/meta DTO fields). The note pins the exact code-vs-table mismatch (dbes/dao/mappings vs the in-place-edited oss000000008).