Replace agent handoff system with planning-based router (#16003)

## Overview

This PR replaces the dynamic agent handoff system with a more
predictable planning-based router that decides upfront how to handle
multi-agent coordination.

## Major Changes

### 🔄 Architecture Shift: Handoffs → Planning

**Removed:**
- `AgentHandoffEntity` and handoff tracking system
- `AgentHandoffService` and `AgentHandoffExecutorService`
- Dynamic agent-to-agent transfers during execution
- Handoff tool generation and description templates

**Added:**
- `AiRouterService` with two strategies: `simple` (single agent) and
`planned` (multi-agent)
- `AgentPlanExecutorService` for executing multi-step plans
- Plan validation (cycle detection, dependency resolution)
- `UnifiedRouterResult` type with discriminated union

### 🤖 New Standard Agents

Added two new specialized agents:
- **Researcher Agent**: Web search, fact-finding, competitive
intelligence
- **Code Agent**: TypeScript function generation for serverless
workflows

### 🏗️ Router Refactoring (Latest)

Split router responsibilities into focused services:
- `AiRouterStrategyDeciderService`: Decides simple vs planned strategy
- `AiRouterPlanGeneratorService`: Generates and validates execution
plans
- `AiRouterService`: Coordinates between services (reduced from 426→275
lines)

### ⚙️ Configuration Improvements

- Added `outputStrategy` to agent definitions (`direct` vs `synthesize`)
- Removed hardcoded special cases for workflow-builder
- Added `plannerModel` field to workspace entity
- Increased `MAX_STEPS` from 10 to 25 for complex workflows

### 📝 Agent Prompt Refinements

Significantly simplified prompts for better clarity:
- Workflow Builder: 51→36 lines
- Helper: 49→28 lines
- Data Manipulator: Enhanced with sorting guidance

### 🔍 Enhanced Debugging

- Plan reasoning and step count in data message parts
- Router debug info with token usage tracking
- Better logging throughout execution pipeline

## Benefits

1. **Simpler Mental Model**: Router decides upfront vs dynamic transfers
2. **Better Predictability**: Users see the plan before execution
3. **Cleaner Architecture**: SRP with focused services
4. **Configuration Over Code**: Agent behavior via config, not hardcoded
logic
5. **Plan Validation**: Catches invalid dependencies and cycles

## Migration Notes

- Database migration removes `agentHandoff` table
- Adds `plannerModel` column to workspace table
- No API breaking changes (agent endpoints unchanged)

## Testing

- Integration tests updated to remove handoff dependencies
- Agent tool test utilities simplified
- Plan validation covered by new logic

## Next Steps (Future PRs)

- Parallel execution of independent plan steps
- Dynamic re-planning based on results
- Plan caching for common routing patterns
- Error recovery strategies in plan executor

packages/twenty-server/src/database/commands/upgrade-version-command/1-10/1-10-regenerate-search-vectors.command.ts

@@ -9,7 +9,7 @@ import {
   type RunOnWorkspaceArgs,
 } from 'src/database/commands/command-runners/active-or-suspended-workspaces-migration.command-runner';
 import { WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';
-import { SEARCH_VECTOR_FIELD } from 'src/engine/metadata-modules/constants/search-vector-field.constants';
+import { SEARCH_VECTOR_FIELD } from 'src/engine/metadata-modules/search-field-metadata/constants/search-vector-field.constants';
 import { IndexMetadataEntity } from 'src/engine/metadata-modules/index-metadata/index-metadata.entity';
 import { ObjectMetadataEntity } from 'src/engine/metadata-modules/object-metadata/object-metadata.entity';
 import { SEARCH_FIELDS_FOR_CUSTOM_OBJECT } from 'src/engine/twenty-orm/custom.workspace-entity';

packages/twenty-server/src/database/typeorm/core/migrations/common/1763805513241-1763805200000-RemoveAgentHandoffTable.ts

@@ -0,0 +1,36 @@
+import { type MigrationInterface, type QueryRunner } from 'typeorm';
+
+export class RemoveAgentHandoffTable1763805513241
+  implements MigrationInterface
+{
+  name = 'RemoveAgentHandoffTable1763805513241';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP TABLE IF EXISTS "core"."agentHandoff" CASCADE`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "core"."agent" ALTER COLUMN "responseFormat" SET DEFAULT '{"type":"text"}'`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "core"."agent" ALTER COLUMN "responseFormat" DROP DEFAULT`,
+    );
+    await queryRunner.query(`CREATE TABLE "core"."agentHandoff" (
+            "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+            "fromAgentId" uuid NOT NULL,
+            "toAgentId" uuid NOT NULL,
+            "workspaceId" uuid NOT NULL,
+            "description" text,
+            "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+            "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+            "deletedAt" TIMESTAMP WITH TIME ZONE,
+            CONSTRAINT "PK_agentHandoff" PRIMARY KEY ("id"),
+            CONSTRAINT "FK_agentHandoff_fromAgent" FOREIGN KEY ("fromAgentId") REFERENCES "core"."agent"("id") ON DELETE CASCADE,
+            CONSTRAINT "FK_agentHandoff_toAgent" FOREIGN KEY ("toAgentId") REFERENCES "core"."agent"("id") ON DELETE CASCADE,
+            CONSTRAINT "FK_agentHandoff_workspace" FOREIGN KEY ("workspaceId") REFERENCES "core"."workspace"("id") ON DELETE CASCADE
+        )`);
+  }
+}

packages/twenty-server/src/database/typeorm/core/migrations/common/1763997530458-AddFastAndSmartModelsToWorkspace.ts

@@ -0,0 +1,30 @@
+import { type MigrationInterface, type QueryRunner } from 'typeorm';
+
+import {
+  DEFAULT_FAST_MODEL,
+  DEFAULT_SMART_MODEL,
+} from 'src/engine/metadata-modules/ai-models/constants/ai-models.const';
+
+export class AddFastAndSmartModelsToWorkspace1763997530458
+  implements MigrationInterface
+{
+  name = 'AddFastAndSmartModelsToWorkspace1763997530458';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "core"."workspace" ADD "fastModel" character varying NOT NULL DEFAULT '${DEFAULT_FAST_MODEL}'`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "core"."workspace" ADD "smartModel" character varying NOT NULL DEFAULT '${DEFAULT_SMART_MODEL}'`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "core"."workspace" DROP COLUMN "smartModel"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "core"."workspace" DROP COLUMN "fastModel"`,
+    );
+  }
+}

packages/twenty-server/src/database/typeorm/core/migrations/common/1764066845539-coreMigrationCheck.ts

@@ -0,0 +1,17 @@
+import { type MigrationInterface, type QueryRunner } from 'typeorm';
+
+export class CoreMigrationCheck1764066845539 implements MigrationInterface {
+  name = 'CoreMigrationCheck1764066845539';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "core"."agent" ALTER COLUMN "modelId" SET DEFAULT 'default-smart-model'`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "core"."agent" ALTER COLUMN "modelId" SET DEFAULT 'auto'`,
+    );
+  }
+}