feat(chat): add Mastra chat-api prototype and OpenRouter smoke

[rschlaefli]

Summary

• Adds the Mastra-backed chat-api prototype stack and chat app proxy wiring currently on this branch.
• Adds a real OpenRouter DeepSeek V4 Flash smoke runner for chat-api that hits the live SSE endpoint and checks streamed text deltas, finish metadata, persisted messages, and credit decrement.
• Adds a GitHub Actions workflow that provisions Postgres, seeds test data, starts chat-api, and executes the OpenRouter smoke. The smoke step is non-blocking for now and falls back to an invalid ci-placeholder value until OPENROUTER_API_KEY is configured as a repository secret.

Verification

• pnpm --filter @klicker-uzh/chat-api check
• Pre-commit hook: pnpm run check:all
• Pre-push hook: pnpm run build
• Local live smoke against OpenRouter DeepSeek V4 Flash on 2026-06-17: textDeltaParts=9, creditsUsed=0.00058458, threadId=b89bda77-bbe6-4685-a03f-21098018c8a9

Notes

• First CI smoke execution is intentionally allowed to continue on failure because the workflow currently uses the placeholder key when the repository secret is absent.
• Next hardening step is to wire OPENROUTER_API_KEY as a repo or environment secret, confirm the workflow passes, then remove continue-on-error from the smoke step.
• The first smoke targets core text streaming, metadata, persistence, and credits. MCP tool-part, image, multi-turn, and Azure reasoning parity smokes are still planned follow-ups.

ClickUp Links

This was generated by AI during triage.

• Primary task: Mat Vorkurs prototype by 2026-06-30

[gitguardian]

⚠️ GitGuardian has uncovered 2 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
14050276	Triggered	Generic Password	1392f31	.github/workflows/playwright-testing.yml	View secret
1509424	Triggered	Generic Password	1392f31	.github/workflows/playwright-testing.yml	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[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

Run ID: c3f7f576-125d-40bf-9d1d-7e840c098401

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

---

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.}

[greptile-apps]

Confidence Score: 3/5

The proxy and engine integration are solid, but the credit accounting layer has a concurrency gap that allows under-charging under load, and thread deletion is non-atomic.

Two present defects in the credit accounting path: (1) atomicDecrementCredits uses a read-modify-write pattern at ReadCommitted isolation, so concurrent chat requests can race and only deduct a single credit's worth regardless of how many responses complete simultaneously; (2) deleteThread deletes messages and then the thread in two separate calls with no transaction, leaving the DB inconsistent on a crash between them. Both issues are on newly introduced code paths that will be exercised in production. The rest of the service — auth, disclaimer gating, MCP toolset, streaming wiring, and the Next.js proxy — is well-structured and closely tracks the existing route.

apps/chat-api/src/utils/transactions.ts (credit decrement atomicity) and apps/chat-api/src/services/threads.ts (non-atomic delete) need attention before the flag is flipped to production.

Important Files Changed

Filename	Overview
apps/chat-api/src/utils/transactions.ts	Atomic credit operations: atomicDecrementCredits uses ReadCommitted isolation with a read-modify-write pattern, making it vulnerable to lost updates under concurrent chat requests. The retry logic targets serialization_failure which never fires at ReadCommitted, leaving concurrent decrements silently under-charging.
apps/chat-api/src/services/threads.ts	Thread CRUD service: deleteThread deletes messages then thread in two separate non-transactional calls; a failure between them leaves orphaned messages. Other methods are clean.
apps/chat-api/src/index.ts	Core Hono service handler: mirrors the Next.js chat route step-for-step with Mastra engine. Body limit guard, auth, disclaimer gate, model selection, image pipeline, MCP toolset, streaming, and persistence are all present. The credit-gating logic is duplicated inline rather than using the exported getModelsForChatbot helper, creating a divergence risk.
apps/chat-api/src/lib/chatModelRegistry.ts	Model registry with Zod validation, fallback enforcement, and credit-aware selection. getModelsForChatbot is exported but unused by the main handler, which re-implements the same filter inline.
.github/workflows/chat-api-openrouter-smoke.yml	CI workflow provisions Postgres, seeds data, starts chat-api, and runs smoke. The smoke step uses continue-on-error: true permanently, so all failures are silently swallowed until the API key secret is wired.
apps/chat-api/src/services/credits.ts	Credit lifecycle service: initializes, resets, and decrements credits, delegating to atomic helpers. Reset idempotency is reasonable given fixed-period alignment, but underlying transaction atomicity issues exist in transactions.ts.
apps/chat-api/src/smoke/openrouterDeepseekV4Flash.ts	Live smoke test against OpenRouter: validates SSE text-delta parts, finish metadata, persistence of user + assistant messages, and credit decrement. Pre-flight environment assertions are thorough.
apps/chat/src/app/api/chatbots/[chatbotId]/chat/route.ts	Next.js chat route: adds a flag-gated proxy path to the new Mastra chat-api service when CHAT_USE_MASTRA_ENGINE is set. Proxy correctly forwards cookies and body, and propagates the abort signal for partial-credit accounting.
apps/chat-api/src/lib/auth.ts	JWT + participation auth chain, closely mirroring the Next.js guard. UUID validation on chatbotId, clean error tuple pattern.
packages/chat-engine/src/agent.ts	Mastra agent builder: per-chatbot provider resolution, primary+fallback model list, Responses API surface. responsesProviderOptions is a clean single source of truth for reasoning engagement.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant NextRoute as apps/chat route.ts
    participant ChatAPI as chat-api (Hono)
    participant Auth as auth.ts
    participant Credits as CreditsService
    participant Engine as chat-engine (Mastra Agent)
    participant DB as PostgreSQL
    participant LLM as OpenRouter / Azure

    Client->>NextRoute: POST /api/chatbots/:id/chat
    alt "CHAT_USE_MASTRA_ENGINE=true"
        NextRoute->>ChatAPI: proxy (body + cookies + abort signal)
        ChatAPI->>Auth: withChatbotAuth(token, chatbotId)
        Auth->>DB: JWT verify + participation check
        Auth-->>ChatAPI: participantId
        ChatAPI->>DB: checkDisclaimerStatus
        ChatAPI->>Credits: getUserCredits (reset if period expired)
        Credits->>DB: upsert / atomic update
        ChatAPI->>DB: fetch chatbot + MCP configs
        ChatAPI->>Engine: buildAgent + agent.stream(messages)
        Engine->>LLM: Responses API (SSE)
        LLM-->>Engine: token stream
        Engine-->>ChatAPI: onChunk / onStepFinish / onFinish / onAbort
        ChatAPI->>DB: persist user + assistant messages
        ChatAPI->>Credits: decrementCredits
        ChatAPI-->>NextRoute: SSE (UI message stream)
        NextRoute-->>Client: SSE proxy
    else legacy path
        NextRoute->>DB: auth + chatbot fetch
        NextRoute->>LLM: streamText (AI SDK)
        LLM-->>NextRoute: token stream
        NextRoute-->>Client: SSE
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client
    participant NextRoute as apps/chat route.ts
    participant ChatAPI as chat-api (Hono)
    participant Auth as auth.ts
    participant Credits as CreditsService
    participant Engine as chat-engine (Mastra Agent)
    participant DB as PostgreSQL
    participant LLM as OpenRouter / Azure

    Client->>NextRoute: POST /api/chatbots/:id/chat
    alt "CHAT_USE_MASTRA_ENGINE=true"
        NextRoute->>ChatAPI: proxy (body + cookies + abort signal)
        ChatAPI->>Auth: withChatbotAuth(token, chatbotId)
        Auth->>DB: JWT verify + participation check
        Auth-->>ChatAPI: participantId
        ChatAPI->>DB: checkDisclaimerStatus
        ChatAPI->>Credits: getUserCredits (reset if period expired)
        Credits->>DB: upsert / atomic update
        ChatAPI->>DB: fetch chatbot + MCP configs
        ChatAPI->>Engine: buildAgent + agent.stream(messages)
        Engine->>LLM: Responses API (SSE)
        LLM-->>Engine: token stream
        Engine-->>ChatAPI: onChunk / onStepFinish / onFinish / onAbort
        ChatAPI->>DB: persist user + assistant messages
        ChatAPI->>Credits: decrementCredits
        ChatAPI-->>NextRoute: SSE (UI message stream)
        NextRoute-->>Client: SSE proxy
    else legacy path
        NextRoute->>DB: auth + chatbot fetch
        NextRoute->>LLM: streamText (AI SDK)
        LLM-->>NextRoute: token stream
        NextRoute-->>Client: SSE
    end

Loading

_{Reviews (1): Last reviewed commit: "test(chat-api): add openrouter smoke wor..." | Re-trigger Greptile}

[greptile-apps]

Lost-update in credit decrement under ReadCommitted isolation

atomicDecrementCredits reads current, computes newCurrent = Math.max(0, current - amount), then writes back — all within a ReadCommitted transaction. Under ReadCommitted, two concurrent requests can both execute the findUnique and see the same balance (e.g. 100), independently compute 99.5, and both write 99.5. Only one credit's worth of tokens is deducted instead of two. The retry helper (isRetryableError) checks for serialization_failure and deadlock, but those errors only arise at SERIALIZABLE isolation; they will never trigger here, so retries provide no protection.

The fix is either to raise the isolation to SERIALIZABLE (which does pair correctly with the existing retry logic) or to replace the read-modify-write with an atomic SQL update (UPDATE ... SET current = GREATEST(0, current - $amount) WHERE pk = ...) that requires no transaction at all.

[greptile-apps]

Non-atomic thread deletion can leave orphaned messages

deleteThread executes two separate, un-transacted Prisma calls: chatMessage.deleteMany followed by chatThread.delete. If the service crashes or the Prisma client throws between the two statements, messages are permanently deleted while the thread record remains, leaving the DB in an inconsistent state. Because there's no $transaction([...]) wrapping both operations, there is no rollback path.

Additionally, the ownership check (getThreadById) and the deletes are not within the same transaction, so a concurrent transfer (if ever supported) could shift ownership between the check and the delete. Wrapping both deletes in prisma.$transaction([chatMessage.deleteMany(...), chatThread.delete(...)]) eliminates both hazards.

[greptile-apps]

getModelsForChatbot is exported but never called from the main handler

getModelsForChatbot encapsulates the full credit-aware allow-list filter (registry → chatbot allow-list → zero-credit fallback), but index.ts reimplements this filtering inline across lines 317–368 instead of delegating to this helper. The two paths can silently diverge if one is updated without the other. Either index.ts should call getModelsForChatbot, or the helper should be removed to avoid confusion about which is authoritative.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

continue-on-error: true silently masks smoke regressions

The smoke step is non-blocking regardless of exit code, so any regression in streaming, persistence, or credit decrement will cause the workflow to succeed and produce a green check on the PR. PRs that break the live SSE path will merge undetected until the OPENROUTER_API_KEY secret is wired and continue-on-error is removed. Consider using if: ${{ secrets.OPENROUTER_API_KEY != '' }} to skip the step entirely when the secret is absent, and removing continue-on-error so a present secret always produces a hard gate.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Too many files changed for review. (182 files found, 100 file limit)

Bypass the limit by tagging @greptile-apps to review.

[rschlaefli]

Review pushed: project/reviews/2026-07-06-pr5126-mastra-chat-api-review.md — full findings with evidence and an ordered, junior-executable production-readiness roadmap.

Headlines:

• P0: PR base is wrong — branch stacks on v3-ai (merge-base 1c97210), so 181 files show against v3 vs an own delta of 87. Retarget with gh pr edit 5126 --base v3-ai (or sequence after feat: AI enhancements #5092).
• P0: apps/chat-api has Traefik routing but no Dockerfile/compose/deploy manifests — cannot ship.
• P0: prototype/mastra-chat (own package.json + two lockfiles) should not merge into a long-lived branch — archive it.
• P1: ~850 lines duplicated verbatim between apps/chat and apps/chat-api (threads.ts is a 0-diff copy); smoke CI is green-but-fake until the OPENROUTER_API_KEY secret is wired and continue-on-error removed.

Code quality of the service path itself is high — see 'What is good' in the review.