TJWaterAgent/.github/copilot-instructions.md

Copilot Instructions for TJWaterAgent

Overview

• TJWaterAgent is a Bun + TypeScript backend service.
• Main entrypoint: src/server.ts
• Chat API base path: /api/v1/agent/chat
• Persistent storage is PostgreSQL-first. Historical file storage only remains for one-time migration and external result payload files.

Core identity model

• sessionId = durable chat thread identifier exposed to clients and used for persistence.
• runtimeSessionId = temporary opencode runtime execution identifier for a single active request.
• Do not reintroduce conversationId / clientSessionId naming for the durable thread id. Use sessionId.

Persistence design

Canonical PostgreSQL tables:

• conversations
• conversation_states
• conversation_turns
• runtime_sessions
• learning_states
• result_refs
• memories

conversations

Stores durable thread metadata:

• session_id
• actor / owner / project fields
• parent_session_id
• title
• status
• streaming lifecycle fields:
  • is_streaming
  • active_runtime_session_id
  • streaming_started_at

is_streaming is persisted so the frontend can recover streaming state after refresh. Stream cleanup must be guarded by active_runtime_session_id so an old stream cannot clear a newer one.

conversation_states

Stores frontend-facing session UI state:

• messages
• branch_groups
• is_title_manually_edited

conversation_turns

Stores transcript turns as one row per turn:

• keyed by turn_id
• linked by session_id
• ordered by deterministic turn_index

Do not fall back to legacy transcript files in runtime code.

runtime_sessions

Stores runtime binding context for internal tools and learning review/gate flows:

• runtime_session_id
• session_id
• actor / project / trace fields
• allow_learning_write
• learning_mode
• released_at

This replaces the old alias-based tool_session_contexts model.

result_refs

result_refs is metadata-only in PostgreSQL:

• metadata lives in PG
• payload body lives outside PG via payload_path or future object_key

Most payloads are large, so do not inline them into PostgreSQL.

memories

Durable memory is stored in PG, not markdown files.

Runtime flow

1. Client sends/loads a session_id.
2. ChatSessionBridge binds that durable sessionId to a fresh runtimeSessionId.
3. Internal tools call back into the server using runtimeSessionId.
4. Transcript, memory, learning state, and result refs persist against sessionId.
5. Stream start sets conversations.is_streaming = true; stream completion clears it only if the runtime id still matches.

Important files

• src/server.ts - bootstrap, internal tool endpoints, app wiring
• src/chat/sessionBridge.ts - sessionId vs runtimeSessionId binding
• src/db/index.ts - PostgreSQL bootstrap and schema migration/cleanup
• src/conversations/store.ts - durable session metadata + streaming state
• src/conversations/stateStore.ts - UI state persistence
• src/history/store.ts - transcript persistence
• src/session/runtimeSessionStore.ts - runtime session persistence
• src/results/store.ts - metadata-only result refs + external payload files
• src/results/resolver.ts - result ref normalization and retrieval
• src/learning/orchestrator.ts / src/learning/stateStore.ts - learning review pipeline
• src/memory/store.ts - persistent memory store
• scripts/migrate-file-storage-to-postgres.ts - one-time migration from legacy file storage

Compatibility rules

• Runtime code should target the canonical schema only.
• Legacy column/table handling belongs only in src/db/index.ts bootstrap migration or scripts/migrate-file-storage-to-postgres.ts.
• Do not add back file-based runtime persistence or compatibility reads unless a migration explicitly requires it.

Validation

Useful commands:

bun run check
PGHOST=... PGPORT=... PGUSER=... PGPASSWORD=... PGDATABASE=agent PGSSLMODE=disable bun test tests/conversations/store.test.ts tests/history/store.test.ts tests/session/runtimeSessionStore.test.ts tests/results/store.test.ts tests/routes/chatSession.test.ts