AI Prompt Guide: The Execution Manual

As a full-stack AI developer, your task is to build the backend foundation for a 2D simulation game using Convex and TypeScript.
 
**Phase 1 Goal:** Create the core database schema and a persistent simulation engine.
 
**Detailed Requirements:**
 
1.  **Database Schema (`convex/aiTown/schema.ts`):**
    *   Define a `worlds` table to store the state of a single game world, including maps of players, agents, and conversations.
    *   Define `players` and `agents` tables (or schemas for serialization) that include position (`x`, `y`) and a unique ID.
    *   Define an `engines` table in `convex/engine/schema.ts` to track the running state of a simulation, including `running` (boolean) and `lastStepTs` (timestamp).
 
2.  **Abstract Game Engine (`convex/engine/abstractGame.ts`):**
    *   Create an `AbstractGame` class with an abstract `tick()` method and a concrete `runStep()` method that manages a loop of ticks.
 
3.  **Concrete Game Implementation (`convex/aiTown/game.ts`):**
    *   Create a `Game` class that extends `AbstractGame`.
    *   Implement the `tick()` method. For now, it can just log the current time. It should iterate through players and agents.
    *   Implement a static `load()` method to fetch all required data from the database for a given `worldId`.
    *   Implement a `saveDiff()` method to persist changes back to the database.
 
4.  **Engine Runner (`convex/aiTown/main.ts`):**
    *   Implement an `internalAction` named `runStep`. This function should:
        a. Load the game state using `Game.load()`.
        b. Run the simulation for a fixed duration by repeatedly calling `game.tick()`.
        c. Save the updated state using `Game.saveDiff()`.
        d. Schedule the next `runStep` to run immediately using `ctx.scheduler.runAfter(0, ...)`.
    *   Implement mutations `startEngine` and `stopEngine` to control the `running` flag in the `engines` table.
 
5.  **Cron Job (`convex/crons.ts`):**
    *   Set up a cron job that runs every minute to call a function like `restartDeadWorlds`, which would find any non-running engines and call `startEngine` on them.
 
Please generate the code for these files, ensuring they are type-safe and follow Convex best practices.

As a frontend AI developer, your task is to build the user interface for the AI Town simulation using React, TypeScript, and Pixi.js. The backend is already set up on Convex.
 
**Phase 2 Goal:** Render the game world and enable a user to join and move their character.
 
**Detailed Requirements:**
 
1.  **Project Setup:**
    *   Use Vite with the React + TypeScript template.
    *   Install dependencies: `react`, `pixi.js`, `@pixi/react`, `convex`.
 
2.  **Backend Connection (`src/components/ConvexClientProvider.tsx`):**
    *   Create a provider component that initializes the `ConvexReactClient` and wraps the main `App` component.
 
3.  **Main UI Components (`src/App.tsx`, `src/components/Game.tsx`):**
    *   `App.tsx` should set up the main layout.
    *   `Game.tsx` should be the primary component for the game screen. It must:
        a. Use the `useQuery` hook from `convex/react` to fetch the current `worldState` from the backend.
        b. Pass this state down to the rendering component.
 
4.  **Rendering Engine (`src/components/PixiGame.tsx`):**
    *   This component will host the Pixi.js application.
    *   Use `@pixi/react` components like `<Stage>` and a custom `<PixiViewport>` for a zoomable/pannable camera.
    *   Render a static map based on map data from the `worldState`.
    *   Iterate through the `players` array from the `worldState` and render a `<Player>` component for each.
 
5.  **Character Rendering (`src/components/Player.tsx`, `src/components/Character.tsx`):**
    *   The `Player` component will receive a single player's data.
    *   The `Character` component will take position, texture, etc., and render an animated sprite using `AnimatedSprite` from `@pixi/react`.
 
6.  **Click-to-Move Interaction:**
    *   In `PixiGame.tsx`, add a pointer-up event handler to the map.
    *   Inside the handler, convert the screen click coordinates to world coordinates.
    *   Implement a custom hook `useSendInput('moveTo')` that calls the `moveTo` mutation on the Convex backend.
    *   Use this hook to send the destination coordinates to the backend when the user clicks the map.

As an AI backend developer, your task is to implement the cognitive architecture for generative agents in AI Town using Convex and an LLM provider like OpenAI.
 
**Phase 3 Goal:** Give agents memory and the ability to hold context-aware conversations.
 
**Detailed Requirements:**
 
1.  **LLM Utility (`convex/util/llm.ts`):**
    *   Create a centralized function `chatCompletion(prompt, messages, stop_words)` to call the LLM API.
    *   Create a function `fetchEmbedding(text)` to get vector embeddings for a piece of text.
    *   Use environment variables for the API key.
 
2.  **Memory Schema (`convex/agent/schema.ts`):**
    *   Define a `memories` table to store memory description, importance score, and type.
    *   Define a `memoryEmbeddings` table to store vector embeddings. It should have a `vectorIndex` configured on the `embedding` field.
 
3.  **Memory Creation (`convex/agent/memory.ts`):**
    *   Implement an `action` called `rememberConversation`. It should:
        a. Take a `conversationId` as input.
        b. Fetch the conversation log.
        c. Call the LLM to summarize the conversation from the agent's perspective.
        d. Call the LLM with a "judge" prompt to rate the summary's poignancy (0-9).
        e. Call `fetchEmbedding` on the summary text.
        f. Save the memory (description, importance) and the embedding to the database.
 
4.  **Memory Retrieval (RAG) (`convex/agent/memory.ts`):**
    *   Implement a query `searchMemories`. It should:
        a. Take a search query text and a player ID.
        b. Get the embedding for the search query.
        c. Use `ctx.db.vectorSearch()` on the `memoryEmbeddings` table to find the most similar memories.
        d. Implement a ranking algorithm that scores memories based on a weighted sum of relevance (from vector search), importance (stored score), and recency (time since last access).
        e. Return the top-ranked memories.
 
5.  **Dialogue Generation (`convex/agent/conversation.ts`):**
    *   Implement an `action` called `agentGenerateMessage`. It should:
        a. Take `playerId`, `otherPlayerId`, and `conversationId` as input.
        b. Fetch the agent's identity, plan, and conversation history.
        c. Call `searchMemories` to retrieve relevant memories.
        d. Construct a detailed system prompt including all this context.
        e. Call `chatCompletion` to get the dialogue.
        f. Return the generated text.

As an AI backend developer, your task is to implement the autonomous behavior for the AI agents in AI Town.
 
**Phase 4 Goal:** Make agents decide and act on their own, including moving and starting conversations.
 
**Detailed Requirements:**
 
1.  **Agent State Machine (`convex/aiTown unbelievability/agent.ts`):**
    *   Implement the `tick(game, now)` method for the `Agent` class.
    *   This method should function as a state machine. Use a property like `agent.inProgressOperation` to track long-running AI tasks.
    *   If the agent is idle (not moving, not in a conversation, no operation in progress), it should schedule an `agentDoSomething` operation.
    *   If the agent is in a conversation, it should handle the logic for its turn (e.g., if enough time has passed, schedule an `agentGenerateMessage` operation).
 
2.  **Autonomous Decision Making (`convex/agent/agentOperations.ts`):**
    *   Implement the `agentDoSomething` `internalAction`. This function should:
        a. Take the `agentId` as input.
        b. Find nearby players who are available for conversation.
        c. Use an LLM to make a high-level choice:
            i.  **Option 1: Start a conversation.** The LLM should choose a specific player to talk to. The action should return the `invitee` ID.
            ii. **Option 2: Wander.** The LLM should decide on a general activity. The action should return a destination point.
    *   The `finishDoSomething` input handler (in `agentInputs.ts`) should process the result: if an `invitee` is returned, it starts a conversation; if a `destination` is returned, it moves the player.
 
3.  **Conversation Lifecycle (`convex/aiTown/conversation.ts`):**
    *   Implement the full state transitions for a conversation.
    *   When an agent receives an invite, its `tick()` method should decide whether to `acceptInvite` or `rejectInvite`.
    *   When an invite is accepted, both agents should use the pathfinding system to walk towards each other.
    *   When they are close enough (`CONVERSATION_DISTANCE`), their state should change to `participating`.
 
Please generate the code for these modules, focusing on the agent's state management and the orchestration of AI-powered decisions.