Add Supabase Edge Functions and shared agent utilities

Initial commit of Supabase Edge Functions, including deployment script, agent completion check utilities, agent self-invoke/retry logic, AI provider abstraction, and supporting documentation. Adds core agent, coordinator, portfolio, and rebalance manager functions, shared helpers, and analysis documentation for Alpaca close position endpoint. Enables modular agent workflows and robust error/retry handling.

Author: BWJ2310

supabase/deploy-functions.sh

@@ -0,0 +1,88 @@
+/Users/bruzwj/Downloads/.env.local#!/bin/bash
+
+# Deployment script for Supabase Edge Functions
+# Run this when Docker is working properly
+if [ -f .env.local ]; then
+  # Load environment variables, handling = signs and quotes properly
+  set -a
+  source .env.local
+  set +a
+fi
+
+echo "🚀 Deploying Supabase Edge Functions..."
+
+# Debug: Check if variables are loaded
+echo "Debug: SUPABASE_ACCESS_TOKEN is ${#SUPABASE_ACCESS_TOKEN} characters long"
+echo "Debug: SUPABASE_PROJECT_REF = $SUPABASE_PROJECT_REF"
+
+# Ensure variables are set
+if [ -z "$SUPABASE_ACCESS_TOKEN" ]; then
+  echo "Error: SUPABASE_ACCESS_TOKEN not found in .env.local"
+  exit 1
+fi
+
+if [ -z "$SUPABASE_PROJECT_REF" ]; then
+  echo "Error: SUPABASE_PROJECT_REF not found in .env.local"
+  exit 1
+fi
+
+# Deploy functions that require --no-verify-jwt flag
+no_verify_jwt_functions=(
+  "alpaca-batch"
+  "alpaca-proxy"
+  "settings-proxy"
+  "execute-trade"
+  "analysis-coordinator"
+  "rebalance-coordinator"
+  "send-invitation"
+  "discord-role-sync"
+  "stripe-webhook"
+  "create-smart-session"
+)
+
+echo "📦 Deploying functions with --no-verify-jwt flag..."
+for func in "${no_verify_jwt_functions[@]}"; do
+  echo "  📦 Deploying $func..."
+  SUPABASE_ACCESS_TOKEN=$SUPABASE_ACCESS_TOKEN npx supabase functions deploy $func --project-ref $SUPABASE_PROJECT_REF --no-verify-jwt
+done
+
+# Deploy functions that use standard JWT verification
+standard_functions=(
+  "process-scheduled-rebalances"
+  "detect-stale-analysis"
+  "auto-near-limit-analysis"
+)
+
+echo "📦 Deploying functions with standard JWT verification..."
+for func in "${standard_functions[@]}"; do
+  echo "  📦 Deploying $func..."
+  SUPABASE_ACCESS_TOKEN=$SUPABASE_ACCESS_TOKEN npx supabase functions deploy $func --project-ref $SUPABASE_PROJECT_REF
+done
+
+# Deploy all agent functions
+agents=(
+  "agent-macro-analyst"
+  "agent-market-analyst"
+  "agent-news-analyst"
+  "agent-social-media-analyst"
+  "agent-fundamentals-analyst"
+  "agent-bull-researcher"
+  "agent-bear-researcher"
+  "agent-research-manager"
+  "agent-trader"
+  "agent-risky-analyst"
+  "agent-safe-analyst"
+  "agent-neutral-analyst"
+  "agent-risk-manager"
+  "analysis-portfolio-manager"
+  "rebalance-portfolio-manager"
+  "opportunity-agent"
+)
+
+echo "📦 Deploying agent functions..."
+for agent in "${agents[@]}"; do
+  echo "  📦 Deploying $agent..."
+  SUPABASE_ACCESS_TOKEN=$SUPABASE_ACCESS_TOKEN npx supabase functions deploy $agent --project-ref $SUPABASE_PROJECT_REF
+done
+
+echo "✅ All functions deployed successfully!"

supabase/functions/CLOSE_POSITION_ANALYSIS.md

@@ -0,0 +1,169 @@
+# Alpaca Close Position Endpoint Analysis
+
+## Current Implementation Review
+
+### 1. Current SELL Order Flow
+
+The Trading Goose currently handles position closing through the following mechanism:
+
+1. **Position Management Detection** (`_shared/positionManagement.ts`):
+   - When a SELL order's dollar amount exceeds the position value OR is within 5% of it
+   - The system converts the order from dollar-based to share-based
+   - Sets `shares` to the total shares in the position
+   - Clears the `dollarAmount` field
+
+2. **Order Submission** (`execute-trade/index.ts`):
+   - Submits a market SELL order to Alpaca using POST /v2/orders
+   - Uses either `notional` (dollar amount) or `qty` (shares) parameter
+   - For full position closures, uses `qty` with all shares
+
+### 2. Alpaca's Close Position Endpoint
+
+Alpaca provides a dedicated endpoint for closing positions:
+- **Endpoint**: `DELETE /v2/positions/{symbol_or_asset_id}`
+- **Purpose**: Immediately liquidates the entire position
+- **Benefits**:
+  - Guaranteed to close the entire position
+  - No need to track exact share count
+  - Handles fractional shares automatically
+  - Single API call with clear intent
+
+## Pros and Cons Analysis
+
+### Using DELETE /positions Endpoint
+
+**Pros:**
+1. **Simplicity**: Single API call that guarantees full position closure
+2. **Accuracy**: No risk of leaving fractional shares behind
+3. **Clarity**: Explicit intent to close position vs. partial sell
+4. **Error Reduction**: No need to calculate or track exact share counts
+5. **Consistency**: Works identically for whole and fractional share positions
+6. **API Efficiency**: Purpose-built for this exact use case
+
+**Cons:**
+1. **Limited Flexibility**: Can only close entire position (no partial capability)
+2. **Different Response Format**: Returns position data instead of order data
+3. **Tracking Complexity**: Need different handling for order tracking/status
+4. **No Order ID**: Doesn't create a traditional order, making tracking harder
+5. **Database Schema Impact**: Current system expects alpaca_order metadata
+
+### Current Approach (SELL all shares)
+
+**Pros:**
+1. **Unified Handling**: Same flow for partial and full sells
+2. **Order Tracking**: Creates standard order with ID for tracking
+3. **Status Polling**: Can monitor order status consistently
+4. **Database Compatibility**: Fits existing schema without changes
+
+**Cons:**
+1. **Fractional Share Risk**: Might leave tiny fractional amounts
+2. **Race Conditions**: Share count might change between read and submit
+3. **Complexity**: Requires accurate share count tracking
+4. **Two-Step Process**: Must fetch position first, then submit order
+
+## Recommendations
+
+### Recommended Approach: Hybrid Solution
+
+Implement a hybrid approach that uses the close position endpoint when appropriate:
+
+```typescript
+// Pseudocode for hybrid approach
+if (shouldCloseFullPosition && userPreference.useCloseEndpoint) {
+  // Use DELETE /positions for clean full closure
+  await closePositionViaDelete(ticker);
+  // Create synthetic order record for tracking
+} else {
+  // Use existing SELL order flow
+  await submitSellOrder(shares || dollarAmount);
+}
+```
+
+### Implementation Strategy
+
+#### Phase 1: Add Close Position Capability (Low Risk)
+1. Create new function `closePositionViaAlpaca()` in `_shared/alpacaClient.ts`
+2. Add configuration option `use_close_endpoint_for_full_sells` in user settings
+3. Modify `execute-trade/index.ts` to check this preference
+
+#### Phase 2: Handle Tracking (Medium Complexity)
+1. Create synthetic order record when using close endpoint
+2. Store close position response in metadata
+3. Mark as immediately "filled" since close is synchronous
+
+#### Phase 3: Improve Position Detection (Enhancement)
+1. Enhance `shouldCloseFullPosition()` logic
+2. Add explicit "CLOSE_POSITION" action type alongside BUY/SELL/HOLD
+3. Allow users to explicitly request position closure
+
+### Migration Plan
+
+```sql
+-- Add user preference for close endpoint usage
+ALTER TABLE api_settings 
+ADD COLUMN use_alpaca_close_endpoint BOOLEAN DEFAULT false;
+
+-- Add tracking for close position operations
+ALTER TABLE trading_actions
+ADD COLUMN close_position_used BOOLEAN DEFAULT false;
+```
+
+### Code Changes Required
+
+1. **New File**: `supabase/functions/_shared/alpacaClosePosition.ts`
+   - Implement close position API call
+   - Handle response and error cases
+   - Create synthetic order tracking
+
+2. **Modify**: `supabase/functions/execute-trade/index.ts`
+   - Check if order should use close endpoint
+   - Route to appropriate execution path
+   - Handle different response formats
+
+3. **Update**: `supabase/functions/_shared/positionManagement.ts`
+   - Add `useCloseEndpoint` flag to validation response
+   - Enhance detection logic
+
+## Risk Assessment
+
+### Low Risk Items
+- Adding new close position function (additive, non-breaking)
+- User preference setting (opt-in feature)
+- Synthetic order creation (backward compatible)
+
+### Medium Risk Items  
+- Routing logic in execute-trade (needs careful testing)
+- Order status tracking differences (requires adaptation)
+- Error handling for new endpoint
+
+### High Risk Items
+- None identified - existing flow remains as fallback
+
+## Conclusion
+
+**Recommendation: Implement the hybrid approach in phases**
+
+The close position endpoint offers clear benefits for full position closures, particularly:
+- Eliminating fractional share remnants
+- Reducing race conditions
+- Simplifying the close process
+
+However, maintaining the existing flow as default ensures:
+- No breaking changes
+- Consistent order tracking
+- Gradual adoption via opt-in
+
+The phased implementation allows for:
+1. Safe introduction of new capability
+2. User testing and feedback
+3. Rollback capability if issues arise
+4. Gradual migration of users
+
+## Next Steps
+
+1. Create migration file for database changes
+2. Implement `alpacaClosePosition.ts` utility
+3. Add routing logic to `execute-trade` function  
+4. Test with paper trading accounts
+5. Create user documentation
+6. Deploy as opt-in beta feature

supabase/functions/_shared/AGENT_TEMPLATE.md

@@ -0,0 +1,134 @@
+# Agent Completion Check Template
+
+This template shows how to add completion checking to prevent duplicate agent execution and save API calls.
+
+## 1. Import the Required Functions
+
+Add this import at the top of your agent file:
+
+```typescript
+import { checkAgentCompletion, checkForBlockingOperations } from '../_shared/agentCompletionCheck.ts'
+```
+
+## 2. Add Completion Check After Initial Setup
+
+After creating the Supabase client and logging initial status, but BEFORE setting up timeouts or doing any actual work, add:
+
+```typescript
+// Check if this agent has already completed for this analysis
+const completionStatus = await checkAgentCompletion(
+  supabase,
+  analysisId,
+  'agent-[YOUR-AGENT-NAME]',  // e.g., 'agent-fundamentals-analyst'
+  '[Your Agent Display Name]'   // e.g., 'Fundamentals Analyst'
+);
+
+if (completionStatus.hasCompleted && completionStatus.status === 'completed') {
+  console.log(`✅ [Agent Name] already completed for analysis ${analysisId}`);
+  console.log(`   Skipping duplicate execution to save API calls`);
+  
+  // Clear any timeout that might have been set
+  if (timeoutId !== null) {
+    clearAgentTimeout(timeoutId, '[Agent Name]', 'already completed');
+  }
+  
+  // Return the existing insights if available
+  return createSuccessResponse({
+    agent: '[Agent Name]',
+    message: 'Agent already completed for this analysis',
+    alreadyCompleted: true,
+    existingInsights: completionStatus.existingInsights,
+    retryInfo: retryStatus
+  });
+}
+
+// Don't check for "already running" - the coordinator handles that before invocation
+// The agent will see itself as "running" because the coordinator marks it as such
+// Only check for "already completed" to avoid re-doing work
+
+// Check for any blocking operations (canceled analysis, etc.)
+const blockingCheck = await checkForBlockingOperations(supabase, analysisId, 'agent-[your-agent-name]');
+if (!blockingCheck.canProceed) {
+  console.log(`🛑 [Agent Name] cannot proceed: ${blockingCheck.reason}`);
+  return createCanceledResponse(
+    `[Agent Name] cannot proceed: ${blockingCheck.reason}`,
+    true
+  );
+}
+```
+
+## 3. Complete Example Structure
+
+```typescript
+serve(async (req) => {
+  let timeoutId: number | null = null;
+  
+  try {
+    // 1. Validate request method and parameters
+    if (req.method !== 'POST') {
+      return createMethodNotAllowedResponse();
+    }
+    
+    const request: AgentRequest = await req.json();
+    // ... parameter validation ...
+    
+    // 2. Initialize Supabase client
+    const supabase = createClient(supabaseUrl, supabaseServiceKey);
+    
+    // 3. Log initial status
+    console.log(`🎯 [Agent Name] starting for ${ticker}`);
+    
+    // 4. ⭐ ADD COMPLETION CHECK HERE ⭐
+    const completionStatus = await checkAgentCompletion(...);
+    // ... handle completion status as shown above ...
+    
+    // 5. Setup timeout (AFTER completion check)
+    timeoutId = setupAgentTimeout(...);
+    
+    // 6. Check cancellation
+    const cancellationCheck = await checkAnalysisCancellation(...);
+    
+    // 7. Do actual work
+    // ... your agent logic ...
+    
+  } catch (error) {
+    // Error handling
+  }
+});
+```
+
+## Agent Names Reference
+
+For the `checkAgentCompletion` function, use these exact names:
+
+| Agent Function Name | Display Name |
+|-------------------|--------------|
+| agent-market-analyst | Market Analyst |
+| agent-news-analyst | News Analyst |
+| agent-social-media-analyst | Social Media Analyst |
+| agent-fundamentals-analyst | Fundamentals Analyst |
+| agent-macro-analyst | Macro Analyst |
+| agent-bull-researcher | Bull Researcher |
+| agent-bear-researcher | Bear Researcher |
+| agent-research-manager | Research Manager |
+| agent-trader | Trader |
+| agent-risky-analyst | Risky Analyst |
+| agent-safe-analyst | Safe Analyst |
+| agent-neutral-analyst | Neutral Analyst |
+| agent-risk-manager | Risk Manager |
+
+## Benefits
+
+1. **Prevents Duplicate Work**: Agents won't re-run if already completed
+2. **Saves API Calls**: No unnecessary AI API calls for completed agents
+3. **Handles Race Conditions**: Prevents concurrent execution of the same agent
+4. **Graceful Recovery**: Allows retry for failed agents while blocking completed ones
+5. **Better User Experience**: Faster responses when agents have already run
+
+## Notes
+
+- The check happens BEFORE setting up timeouts to avoid unnecessary timeout handlers
+- The check happens BEFORE any actual work (API calls, data fetching, etc.)
+- Failed agents (status='error') are allowed to retry
+- Running agents are blocked to prevent concurrent execution
+- Completed agents return their existing insights if available