Merge pull request #35 from jmbish04/feat/deep-research-chat

Feat/deep research chat

Author: jmbish04

.agent/rules/000-bootstrap.md

@@ -0,0 +1,15 @@
+---
+trigger: always_on
+---
+
+# 000: BOOTSTRAP & PROTOCOL CHECK
+**CRITICAL: Mandatory Pre-flight Check.**
+
+Before starting any task, you must verify the following from `AGENTS.md`:
+
+1.  **Workspace Context**: Identify if you are working in `frontend` or `container`. 
+2.  **Installation Protocol**: You MUST use `pnpm add <pkg> --filter <package>` from the root. Never install at root without `-w`.
+3.  **SDK Enforcement**: Verify you are using `@google/genai` (New SDK) and NOT `@google/generative-ai` (Legacy).
+4.  **Backend/Frontend Sync**: If modifying Drizzle schemas, ensure `frontend/src/db` is the target as per the "Schema Sync" section.
+
+**STOP**: If you have not explicitly read `AGENTS.md` in this session, do so now.

.agent/rules/000-core-directive.md

@@ -0,0 +1,21 @@
+---
+trigger: always_on
+---
+
+# CORE DIRECTIVE: PROTOCOL ENFORCEMENT
+
+**CRITICAL:** Before performing ANY task, you MUST synchronize your internal state with the project's specific constraints.
+
+1. **Mandatory Documentation Review:**
+   - You MUST read the `AGENTS.md` file in the root directory. It contains the workspace architecture and pnpm protocols.
+   - You MUST read ALL files in the `.agent/rules/` directory to understand the coding standards (Drizzle, Shadcn, Astro).
+
+2. **Workspace Verification:**
+   - Confirm if the task involves the `frontend` or `root/backend`.
+   - Apply the `pnpm --filter` protocol defined in `AGENTS.md`.
+
+3. **Validation Step:**
+   - If you have not read `AGENTS.md` in the current session, STOP and read it now. 
+   - Failure to follow the `pnpm` installation rules defined in `AGENTS.md` will result in environment corruption.
+
+**DO NOT proceed with code generation until you have confirmed the pnpm workspace structure.**

.agent/rules/ai-providers.md

@@ -0,0 +1,12 @@
+# Protocol: AI Provider Routing & Resolution
+
+**MANDATORY IMPORT PATH**: Agents must _always and exclusively_ import AI functions from `@/ai/providers`.
+**FORBIDDEN IMPORTS**: It is _never_ acceptable to import directly from specific provider files (e.g., `ai/providers/openai`, `ai/providers/gemini`) or the index file explicitly (e.g., `ai/providers/index`).
+
+**FUNCTION USAGE**: When using functions like `generateText`, `generateStructuredResponse`, etc., the agent should specify the `provider` and `model` arguments when known.
+
+**FALLBACK BEHAVIOR**:
+
+- If no provider or model is provided by the caller, the system relies on the `index.ts` routing to default to `worker-ai`, which then utilizes its internal business logic to select the correct fallback model.
+- Similarly, if a provider is specified but no model is provided, the specific provider module's logic determines the default model.
+- Agents should not hardcode default models unless explicitly required by the business logic.

.agent/rules/ai-rules.md

@@ -0,0 +1,14 @@
+# Rule: AI Provider & Structured Responses
+
+## 1. Structured Output Mandate
+
+- **CRYSTAL CLEAR RULE**: ANYTIME the AI model is being instructed to respond with a structured response (JSON), you **MUST** use `generateStructuredResponse` or `generateStructuredWithTools` exported from `@/ai/providers`.
+- **FORBIDDEN**: Do not rely on native Agent SDK schemas (e.g. `outputType: MySchema as any` in `@openai/agents`). These frequently fail to map correctly through the Cloudflare AI Gateway or result in brittle string parsing.
+
+## 2. The Extraction Pattern (Agents with Tools)
+
+If you are running an autonomous Agent that requires tool usage (e.g., `HealthDiagnostician` or `ResearchAgent`):
+
+1. Configure the Agent to output standard text/markdown (`outputType` must NOT be explicitly defined).
+2. Await the Agent's `finalOutput` inside the execution loop.
+3. Pass that string into `generateStructuredResponse` along with your Zod schema (converted via `zodToJsonSchema`) to strictly extract and type the final JSON object. This ensures Gateway compatibility while guaranteeing Zod-verified JSON.

.agent/rules/architecture.md

@@ -0,0 +1,19 @@
+---
+trigger: always_on
+---
+
+# Rule: Architectural Integrity & Communication
+
+## 1. Data Layer Isolation
+- **Backend Only**: Drizzle ORM, D1 bindings, and database migrations MUST reside exclusively in the `backend/` or `packages/db` directory.
+- **Frontend Prohibition**: The `frontend/` folder is strictly forbidden from importing `drizzle-orm`, `drizzle-kit`, or any direct database drivers. 
+- **Action**: If the agent detects a database-related install in the frontend, it must immediately abort and move the logic to a Hono route.
+
+## 2. Communication Standards
+- **Primary Protocol**: Use **Hono RPC** (`hc`) for all standard API interactions. This ensures shared type definitions between the Hono `AppType` and the Astro/React frontend.
+- **Real-time Status**: For long-running tasks (e.g., AI generation, PR creation), use **WebSockets** (via Durable Objects) or **Server-Sent Events (SSE)**.
+- **Type Safety**: Never manually redefine backend response types in the frontend. Always export the `AppType` from the backend and import it into the frontend's API client.
+
+## 3. Operational Flow
+- All frontend data fetching must go through a centralized `src/lib/api-client.ts` that initializes the Hono RPC client.
+- Status updates for background jobs must be pushed from the backend to the frontend, rather than the frontend polling the database.

.agent/rules/config-standards.md

@@ -0,0 +1,6 @@
+# Configuration Standards
+
+- **KV First**: Always attempt to retrieve configuration from `KV_CONFIGS` via the `ConfigManager` before falling back to `c.env`.
+- **Type Safety**: Any new configuration key MUST be added to the `ConfigSchema` in `src/lib/config.ts`.
+- **Validation**: Use Zod for all incoming config updates.
+- **Sensitive Data**: Never log the actual values of keys retrieved from KV or Env.

.agent/rules/durable_objects.md

@@ -0,0 +1,47 @@
+# Rule: Durable Object & Agent Migration Strategy
+
+## 1. Definition
+
+- **Requirement**: All new Agents and Durable Objects must be explicitly defined in `durable_objects.bindings`.
+- **Constraint**: ALL new classes must be registered in the `migrations` block of `wrangler.jsonc`.
+
+## 2. Deployment Lifecycle Rules
+
+### A. Fresh Deployment (Never Deployed)
+
+- If the worker has **never** been deployed to production, you MAY add new classes to `migrations.v1`.
+
+### B. Standard Deployment (Already Live)
+
+- If the worker **has** been deployed, you **MUST** create a new migration version (e.g., `v2` -> `v3`).
+- **Forbidden**: Do NOT add new classes to existing/previous migration tags (e.g., do not retroactively add to `v1`).
+
+## 3. Configuration Format
+
+- **Field**: Always use `new_sqlite_classes` for Agents/DOs.
+- **Documentation**: Use a docstring comment to explain the purpose of the new class.
+
+### Example
+
+```jsonc
+"migrations": [
+  {
+    "tag": "v1",
+    "new_sqlite_classes": ["ExistingAgent"]
+  },
+  {
+    "tag": "v2",
+    "new_sqlite_classes": [
+      // Specialized agent for handling X
+      "NewSpecializedAgent"
+    ]
+  }
+]
+```
+
+## 4. Checklist
+
+1. [ ] Defined in `durable_objects.bindings`?
+2. [ ] Added to `migrations`?
+3. [ ] Is the migration tag incremented (if live)?
+4. [ ] Is the class name docstringed?

.agent/rules/globals.md

@@ -0,0 +1,35 @@
+# Rule: Global Env Type Enforcement
+
+## 1. Global Definition
+
+- **Requirement**: `Env` is a globally available type generated by `wrangler types`.
+- **Constraint**: DO NOT import `Env` from `worker-configuration` or via relative paths (e.g., `../../../worker-configuration`).
+
+## 2. Type Resolution
+
+- The `Env` interface is automatically augmented by `wrangler types` into `worker-configuration.d.ts`.
+- `tsconfig.json` acts as the source of truth for including these types globally.
+- Usage: simply use `Env` in function signatures or class definitions without imports.
+
+## 3. Forbidden Patterns
+
+- ❌ `import type { Env } from "../../../worker-configuration";`
+- ❌ `import { Env } from "@/worker-configuration";`
+
+## 4. Correct Usage
+
+```typescript
+// ✅ Correct
+export class MyAgent extends WorkerEntrypoint<Env> {
+  // ...
+}
+
+// ✅ Correct
+const handleRequest = async (
+  request: Request,
+  env: Env,
+  ctx: ExecutionContext,
+) => {
+  // ...
+};
+```

.agent/rules/paths.md

@@ -0,0 +1,21 @@
+---
+trigger: always_on
+---
+
+# Rule: Absolute Pathing & Alias Standards
+
+## 1. Path Definition
+- ALWAYS use defined path aliases for cross-module imports. 
+- **Forbidden**: `import { ... } from "../../../db"`
+- **Required**: `import { ... } from "@db/schema"`
+
+## 2. Standard Aliases
+- `@/*`: Maps to the local `src` directory.
+- `@db/*`: Maps to the Drizzle/D1 data layer in the backend.
+- `@api/*`: Maps to the Hono RPC definitions/AppType.
+- `@ui/*`: Maps to the Shadcn component registry.
+- `@shared/*`: Maps to shared Zod schemas and utility functions.
+
+## 3. Configuration Maintenance
+- If the agent creates a new top-level directory (e.g., `services/`), it MUST immediately update `tsconfig.json` and the corresponding bundler config (Vite/Astro) to include the new alias.
+- All path aliases must be reflected in the `backend/` and `frontend/` tsconfigs to ensure the RPC client (`hc`) resolves types without internal relative path leakage.

.agent/rules/realtime.md

@@ -0,0 +1,5 @@
+# Rule: Real-time Communication Standards
+
+- **WebSocket First**: Any UI component requiring a "progress bar" or "agent status" must use WebSockets via Cloudflare Durable Objects.
+- **RPC Only**: Standard REST calls MUST use the Hono RPC client. Manual `fetch('/api/...')` is deprecated and will be flagged as an error.
+- **Shared Schemas**: Input validation schemas (Zod) must live in a shared `packages/schema` or `backend/src/schemas` and be used by both the Hono validator and the RPC client.